Data Services

Data Service is an API data service that makes it easy to build custom APIs.

With "Data Service API", you can turn workspace datasets into usable APIs without writing complex code: just use the menus in the interface to build an API quickly.

Setting up a Data Service

Step 1: Open the Data Service page

On the workspace page, go to the Data Services tab.

Step 2: Enter the API's basic information

Click the Create a Data Service button.

This feature requires the workspace Owner to grant the Create Data Service permission to the user in Workspace Access Control.

Set the Data Service's basic information as follows.

Name: A custom name

Select a Dataset: The dataset to build from

Description: A custom description

URL Path: Custom characters; the system generates the final API URL from the system settings plus these characters.

Cache: Whether to enable caching (pre-caching data), which speeds up API access. Click the Cache button to show the cache schedule settings.

• Schedule: Does not repeat, or Repeats
• Repeat interval: in minutes, hours, days, or weeks

After completing these settings, click Next.

Step 3: Set Parameters, Validation rules, and Response Columns

Click the + button to add a parameter.

You can set multiple parameters. Each parameter has the following fields:

• Required: Whether the parameter is required
• Operator: The condition used to fetch data for the API parameter (equal to / greater than / greater than or equal to / less than / less than or equal to)
• Validation Rules: Validation conditions for the API parameter. If a user passes a value that doesn't meet the rules, an error is returned. Multiple rules can be selected; if a parameter has several, all must be satisfied for the API request to succeed.

info

A parameter can have multiple operators. Click the Add Operation button to add an operator.

For the operators and validation rules supported for each type, see "Supported Parameter Operations and Validation Rules" at the end of this chapter.

Click the Add Operation button to add an operator; a parameter can have multiple operators.

• Response columns: The left side lists the dataset's columns; the right side lists the columns this Data Service returns. Use > and < to add and remove columns.

Step 4: Simulate API results

The system simulates API query results based on your design in the previous step.

info

The simulation shows a small amount of data for spot-checking. If the parameters produce a large result, the system shows part of the data for review.

Click Select Parameters to simulate results with the other parameters set in Step 3. Click the Select Parameters button and enter the parameters to simulate.

• Customize SQL: At this stage you can customize the query as needed, but we strongly recommend that a technical person does this. After entering custom SQL, go back to the previous step and adjust the settings to match your custom SQL; otherwise the Data Service API design and the API documentation will be inconsistent.

Recommended use of Customize SQL: when Step 3 cannot express a complex validation rule, write SQL to add the extra validation logic. Parameter columns should still be selected in Step 3.

warning

DATA SERVICE API only supports converting a single dataset into an API

In Customize SQL you can query multiple datasets, but a Data Service API only supports converting a single dataset into an API. Avoid querying multiple datasets in Customize SQL, or this Data Service API will fail.

info

Simulated results: when using Customize SQL, include parameters in the SQL so the query results can be simulated.

Step 5: API setup complete

Back on the Data Services tab, you can see the Data Service API you just created.

• Click View API Docs to open the API documentation in a new tab; the documentation can also be downloaded.
• Only the creator and the workspace owner can edit or delete it

info

DATA CONSUMERS can only see SEMANTIC data

On the Data Services tab, users with the Data Consumer role in the workspace may not see all of the workspace's Data Service APIs. If a Data Service API is built from a dataset without the semantic setting enabled, Data Consumers cannot see it on this tab.

warning

Removing a DATA SERVICE API creator

If an API creator's account needs to be removed from the platform, all APIs they created must be deleted first before the account can be removed. Data Service APIs can be deleted by the creator or the workspace Owner.

Supported Parameter Operations and Validation Rules

Parameter type	Operator	Validation Rules-1	Validation Rules-2	Validation Rules-3
Boolean	eq(=)	x	x	x
Integer, Fixed-precision, Floating-point	equal to (eq)	Max, Min	x	x
	greater than(gt)	x	x	x
	greater than and equal to (gte)	x	x	x
	less than (lt)	x	x	x
	less than and equal to (lte)	x	x	x
String	equal to (eq)	Max, Min	Format (Regex Pattern)	enum
	like	Max, Min	Format (Regex Pattern)	x
	in	Max, Min	Format (Regex Pattern)	x
Date	equal to (eq)	Format(YYYY-MM-DD)	x	x
	greater than(gt)	Format(YYYY-MM-DD)	x	x
	greater than and equal to (gte)	Format(YYYY-MM-DD)	x	x
	less than (lt)	Format(YYYY-MM-DD)	x	x
	less than and equal to (lte)	Format(YYYY-MM-DD)	x	x
Timestamp	equal to (eq)	Format(YYYY-MM-DD HH:mm:ss)	x	x
	greater than(gt)	Format(YYYY-MM-DD HH:mm:ss)	x	x
	greater than and equal to (gte)	Format(YYYY-MM-DD HH:mm:ss)	x	x
	less than (lt)	Format(YYYY-MM-DD HH:mm:ss)	x	x
	less than and equal to (lte)	Format(YYYY-MM-DD HH:mm:ss)	x	x

API usage

Authorization

Before using a data service, create a Personal Access Token in Canner Enterprise and put the generated token in the request header.

Name	Format	Sample
Authorization	format("canner-pat %s", PAT)	canner-pat asdsafgwg4gregregergergregerg32

Error Handling

Common errors take the following forms.

Status	Description
400	Invalid parameters, e.g. a column that is not in this data service's settings
401	Authorization failed, e.g. an incorrect token or reading an unauthorized workspace
404	Resource not found, e.g. the workspace or Materialized View does not exist