Component: REST data sources
Introduction
REST API is one of the most popular data exchange protocols these days. However, implementing either a good data solution or a REST API is never easy. This component is designed to provide a robust, secure, and convenient way to quickly enable access to your Casewhere data sources.
Features
Configure Endpoints
The component provides an interface for administrating endpoints. Here the end-users can select and decide which data sources are accessible through REST API. It's also possible to configure to only return a subset of your data source by explicitly selecting the fields to respond.
On this configuration page, there are some other functions such as delete, import, export and Postman file download.
When adding or editing an endpoint, the component shows a dialog that allows inputting some information for the endpoint.
Here is a list of input fields:
- Endpoint [required]: A string that is used by the consumer to allocate the endpoint to access. It only can contain alphanumeric characters, hyphens and underscores. Letters in the string can be in uppercase or lowercase.
- Data source name [required]: Data source that provides data for incoming requests to the endpoint
- Description [optional]: You can write anything you want in this field to describe the endpoint
- Active: The endpoint is available or not
- Data source fields: This section shows a list of data fields which belong to the selected data source. For each data field, you are able to configure that it can be read or written
Configure Credentials
To setup authorization for requests, you can define credentials. The component has a Credentials page on the worker site which allows managing credentials.
The data for adding/editing is input on the credential edit dialog.
On the dialog, you can fill in:
- Name [required]: A unique name for a credential to identify different credentials
- Type [required]: Type of the credential. Currently, it only supports two types which are API Key and anonymous. Other types will be implemented later
- Authentication rule [optional]: Optional custom rule to validate the request. On the dialog, this field is selectable with a drop-down. All server rules are listed. Refer to the next section to learn how to implement a rule
- Description [optional]: Give more detail about the credential
Beside those information, each credential's type has its own properties.
For API-key credential, the dialog shows one more property that let the operator to enter or generate an API key.
Configure Permissions
You can setup permissions for endpoints on the Permissions page.
When adding or editing a permission, you have to enter data on the permission edit dialog.
Here is input fields:
- Name [required]: A name to be an alias for the permission. It is not crucial to be unique
- Credential [required]: Select a created credential from the drop-down list
- Endpoints: Permission for each endpoint. Permission for each endpoint can be Read, Write and/or Delete
- Description [optional]: Give more detail about the permission
- Active: The permission is available or not
GET Request
Consumers can make GET requests to retrieve data flexibly. To support flexibility, the component provides a sufficient syntax. Below is a list of parameters that can/must be included in requests.
- $endpoint [required]: Name of an endpoint that the request is made for. Besides, the consumer can define this parameter with an ID of the needed data. Examples:
- /dynamic/datasources?$endpoint='Customer'
- /dynamic/datasources?$endpoint='Customer(Customer/5a2fev1br94rehfefef2)'
- $top [optional]: Maximum number of data records to get
- $skip [optional]: Number of data records that the consumer wants to skip
- $search [optional]: Keyword for full text search. Must be put between a pair of quotes
- $filter [optional]: Condition to query. The filter string follows OData syntax. Refer to OData URI Parser component for supported operators
- $select [optional]: Fields' names separated by commas. Only fields that are configured to be able to read are returned. If this parameter is undefined, the component will respond with all allowed fields
- $orderby [optional]: Define data's order. Can order by multiple fields, separated by commas. Here are two cases:
- Fields that are used to sort in descending order: [Field name] desc
- Otherwise, [Field name]
Example:
[API URL]/dynamic/datasources?$endpoint='Customer'&$top=5&$skip=2&$search='blue'&$filter=Description eq 'lorem ...' and ActiveDate eq 2022-06-04T15:31:36.000Z&$select=Description,ActiveDate&$orderby=CreatedDate desc,ModifiedAt
Response
The component will respond differently for different cases. Here is the table that describes all status codes that are used explicitly by the component.
| Code | Description | Payload |
|---|---|---|
| 200 | Request is valid and data is found | { Data: {...}, TotalCount: 123 } |
| 400 | Request is invalid | Error message if any |
| 401 | Request is unauthorized | |
| 403 | Request to inaccessible endpoint or request is unauthenticated | |
| 404 | Endpoint is not found | |
| 500 | An error occurs when processing the request | Correlation ID and error message if any |
Installation
Requirements
Casewhere 2.6.10 or later
Configuration
- Import the product
- Link configuration pages to your worker sites and configure access control
- Configure endpoints, credentials and permissions
Releases
1.0.0 - 10/08/2022
Changelog
- Configuration pages
- GET endpoint
Download (login required): REST data sources v1.0.0