API
- 1 Authentication
- 2 Environments
- 3 Methods
Authentication
API endpoints are authenticated using standard OAuth 2.0 client credentials. A user’s client id and client secret can be obtained from their profile page in the DataBlend web application.
Note: Regenerating credentials will cause existing credentials to be invalidated and should only be regenerated in the event current credentials are compromised.
To obtain an access token the client id and client secret are sent to the token endpoint of the environment:
POST /oauth2/token HTTP/1.1
Host: {{TOKEN_ENDPOINT}}
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id={{CLIENT_ID}}&client_secret={{CLIENT_SECRET}}The response will contain the access token:
{
"access_token": "{{ACCESS_TOKEN}}",
"expires_in": 3600,
"token_type": "Bearer"
}The access token is then sent in the Authorization header to all API requests:
GET /user-profiles/me HTTP/1.1
Host: {{API_ENDPOINT}}
Authorization: Bearer {{ACCESS_TOKEN}}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 70
Connection: keep-alive
Date: Wed, 18 Mar 2020 13:51:18 GMT
{"name":"Your User Name","id":"your user id"}Unauthenticated requests with no Authorization header or an invalid or expired access token will generate a 401 Unauthorized response.
Environments
Token Endpoints
production |
|
API Endpoints
production |
|
Methods
There are seven main methods used to work with each object type: the basic four REST CRUD operations as well as patch, find and search.
Search
A set of objects can be searched for by POSTing a Search object to an object’s endpoint. The Search object allows users to specify filters, orders and pagination values to limit and sort the results. The original search object is passed back to the response populated with the results.
Note: Most search endpoints return partial objects as results. This is done to reduce overhead and bandwidth. If the full object is needed after a search it can be retrieved by id.
Properties
The search object has four properties that can be set in the request and two that are populated in the response.
Limit
Optional. Integer. Defaults to 10. The maximum number of results that will be returned. Used in conjunction with Offset to page data. Use -1 to return all results or 0 to return none.
Offset
Optional. Integer. Defaults to 0. Determines how many records to offset in the query (eg for the second page of 10 results the offset would be 10).
Orders
Optional. Order[]. Defaults to []. Sorts the results by the paths and orders specified. Multiple orders are applied in sequence.
The order object has two properties
Direction
Required. Natural | Ascending | Descending. Natural denotes no sorting is applied.
Path
Required. String. The field that should be sorted. Nested properties can be used (eg if an object has a property called user and user is an object with a property called name the path could be user.name)
Predicate
Optional. Predicate. Defaults to null. Filters results by specified values.
There are three types of predicates
Property
Used to filter results by comparing a property to a value. Each property predicate has three properties:
Path - Required. String. Same as the path used in orders, used to determine what path of the object to compare the supplied value to. Supports nested properties.
Value - Required. any. Value to compare.
Comparator - Required. NotEqualTo | LessThan | LessThanOrEqualTo | EqualTo | GreaterThanOrEqualTo | GreaterThan. Determines how the path is compared to the property. EqualTo and NotEqualTo can be used on wide range of types while the others are mostly used for number and dates.
Note: EqualTo is case sensitive for strings. If case insensitivity is needed use the Text predicate.
Text
Used to search text within a property. Useful for searching using an autocomplete field. Results are not case sensitive.
Path - Required. String. Same as the path used in orders and Property predicates.
Term - Required. any. Value to compare.
Mode - Required. EqualTo | Anywhere | Start | End. Determines how the term is found in the property.
Junction
Used to logically combine multiple predicates. Other junctions can be used in the predicates field allowing complex logical statements (eg (a and b) or (c and d)).
Type - Required. And | Or. Determines which junction to be used.
Predicates - Optional. Predicate[]. Defaults to []. Any predicates supplied will be and’ed or or’ed together base on the type field.
Total Results
Read-only. Integer. Populated in the response. Gives the total number of results according to the provided predicate regardless of the limit or offset.
Results
Read-only. any[]. Populated in the response. The results of the search.
Request
Search objects are POSTed to an object's /search endpoint. The simplest request is passing an empty json object.
which would return something like
The return search object is populated with the original request (default values populated) as well as the total results and a list of results (removed for brevity).
To search for objects with a value of ‘abc’ anywhere in a property called name and sort the results by name:
To get the next page of 10 results, increase the offset by 10:
To search for objects by name and by some group id:
Multiple orders can be used as well. To sort by group.name then name:
Find
Similar to search, find allows one full object to be retrieved using filtering and ordering. Instead of returning a Search object it will return the first full result that matches the predicate and orders. If no results are found a 404 Not Found will be returned.
Request
would return
Retrieve
Objects can be retrieved by id with a GET request to the object's endpoint
In the event the object is not found a 404 Not Found will be returned
If the id is not a well-formed Guid a 400 Bad Request will be returned
Create
To create an object simply POST it to the object’s endpoint:
It will return the full definition of the object that was created:
Update
To update an object make a PUT request to the object’s endpoint with the id of the object:
Similar to the create method, the full object will be returned in the repsonse. Fields that cannot be changed such as group, created, createdBy, etc do not need to be passed but all required fields do.
Patch
Update
If only the id of an object is known or if only a few fields need to change, a PATCH request can be made to update only certain properties of an object. The format of the body follows the IETF RFC 6902 specification. Another way to update the name of an object as above:
The full updated object will be returned in the response.
Bulk Delete
Multiple objects can be removed at the same time using the remove operation and passing the path as the id of the object to be deleted:
If all objects were deleted successfully a 200 OK will be returned, otherwise a 400 Bad Request will be returned indicating which objects could not be deleted.
Delete
To delete an object make a DELETE request to the object’s id endpoint:
If successful an empty 200 OK response will be returned.