Knowledge Base

Admin

API Basics

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:  Content-Type: application/x-www-form-urlencoded grant_type=client_credentials&client_id=&client_secret=

The response will contain the 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:  Authorization: Bearer  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

https://cognito.ml.datablend.com/oauth2/token

API Endpoints

production

https://api.ml.datablend.com

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.

POST /agents/search HTTP/1.1 Authorization: Bearer Content-Type: application/json Host: {}

which would return

HTTP/1.1 200 OK Date: Mon, 23 Mar 2020 20:49:12 GMT Content-Type: application/json; charset=utf-8 Content-Length: 2270 {"predicate":null,"offset":0,"limit":10,"orders":[],"totalResults":2,"results":[{"lastPing":{"agent":{"name":"test","ownableType":"Agent","created":"2020-01-09T16:42:58.386264Z","updated":"2020-03-12T19:44:49.274592Z","createdBy":{"created":"2019-09-05T21:32:21.698821Z","profile":{"name":"Mike Lindenmuth","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"updatedBy":{"created":"2019-09-05T21:32:21.698821Z","profile":{"name":"Mike Lindenmuth","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"group":{"name":"mlindenmuth@j2interactive.com","created":"2019-09-05T21:32:21.698821Z","currentRole":"Member","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"156ccba4-005c-4f9b-a3d9-cf98effd777b"},"state":"Stopped","lastSeen":"2020-03-12T19:42:52.24207Z","processId":null,"machineName":null,"id":"156ccba4-005c-4f9b-a3d9-cf98effd777b"},"name":"test","ownableType":"Agent","created":"2020-01-09T16:42:58.386264Z","updated":"2020-03-12T19:44:49.274592Z","createdBy":{"created":"2019-09-05T21:32:21.698821Z","profile":{"name":"Mike Lindenmuth","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"updatedBy":{"created":"2019-09-05T21:32:21.698821Z","profile":{"name":"Mike Lindenmuth","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"group":{"name":"mlindenmuth@j2interactive.com","created":"2019-09-05T21:32:21.698821Z","currentRole":"Member","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"156ccba4-005c-4f9b-a3d9-cf98effd777b"},{"lastPing":null,"name":"mike local","ownableType":"Agent","created":"2019-12-05T16:51:37.340785Z","updated":"2019-12-06T18:30:24.753514Z","createdBy":{"created":"2019-09-05T21:32:21.698821Z","profile":{"name":"Mike Lindenmuth","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"updatedBy":{"created":"2019-09-05T21:32:21.698821Z","profile":{"name":"Mike Lindenmuth","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"group":{"name":"Home Base","created":"2019-12-02T20:28:24.716991Z","currentRole":"Member","id":"41b75267-22ac-4227-96d6-6fcf198d22ce"},"id":"4bd7616e-c630-4b7f-b782-aa9636d200b8"}]}

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).

{ "predicate": null, "offset": 0, "limit": 10, "orders": [], "totalResults": 2, "results": [...] }

To search for objects with a value of ‘abc’ anywhere in a property called name and sort the results by name:

{ "predicate": { "path": "name", "term": "abc", "mode": "Anywhere", "id": "name" }, "offset": 0, "limit": 10, "orders": [ { "path": "name", "direction": "Ascending" } ] }

To get the next page of 10 results, increase the offset by 10:

{ "predicate": { "path": "name", "term": "abc", "mode": "Anywhere", "id": "name" }, "offset": 10, "limit": 10, "orders": [ { "path": "name", "direction": "Ascending" } ] }

To search for objects by name and by some group id:

{ "predicate": { "predicates": [ { "path": "group.id", "comparator": "EqualTo", "value": "some-guid", }, { "path": "name", "term": "abc", "mode": "Anywhere", "id": "name" } ], "type": "And" }, "offset": 0, "limit": 10, "orders": [ { "path": "name", "direction": "Ascending" } ] }

Multiple orders can be used as well. To sort by group.name then name:

{ "predicate": { "predicates": [ { "path": "group.id", "comparator": "EqualTo", "value": "some-guid", }, { "path": "name", "term": "abc", "mode": "Anywhere", "id": "name" } ], "type": "And" }, "offset": 0, "limit": 10, "orders": [ { "path": "group.name", "direction": "Ascending" }, { "path": "name", "direction": "Ascending" } ] }

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

{ "predicate": { "predicates": [ { "path": "group.id", "comparator": "EqualTo", "value": "some-guid", }, { "path": "name", "term": "abc", "mode": "Anywhere", "id": "name" } ], "type": "And" }, "orders": [ { "path": "group.name", "direction": "Ascending" }, { "path": "name", "direction": "Ascending" } ] }

would return

{ ...actual definition of object }

Retrieve

Objects can be retrieved by id with a GET request to the object's endpoint

GET /agents/156ccba4-005c-4f9b-a3d9-cf98effd777b HTTP/1.1 Host:  Authorization: Bearer  HTTP/1.1 200 OK Date: Mon, 23 Mar 2020 20:10:10 GMT Content-Type: application/json; charset=utf-8 Content-Length: 675 {"name":"test","ownableType":"Agent","created":"2020-01-09T16:42:58.386264Z","updated":"2020-03-12T19:44:49.274592Z","createdBy":{"created":"2019-09-05T21:32:21.698821Z","profile":{"name":"Mike Lindenmuth","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"updatedBy":{"created":"2019-09-05T21:32:21.698821Z","profile":{"name":"Mike Lindenmuth","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"group":{"name":"mlindenmuth@j2interactive.com","created":"2019-09-05T21:32:21.698821Z","currentRole":"Member","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"156ccba4-005c-4f9b-a3d9-cf98effd777b"}

In the event the object is not found a 404 Not Found will be returned

HTTP/1.1 404 Not Found Date: Mon, 23 Mar 2020 20:09:26 GMT Content-Type: application/json; charset=utf-8 {"message":"Not found"}

Note: Even if an object exists with that id but the current user does not have access to it a 404 will still be returned. This prevents unauthorized users from discovering possible ids by not letting them know something with that id exists.

If the id is not a well-formed Guid a 400 Bad Request will be returned

HTTP/1.1 400 Bad Request Date: Mon, 23 Mar 2020 20:06:28 GMT Content-Type: application/json; charset=utf-8 {"message":"The value 'abc' is not valid."}

Create

To create an object simply POST it to the object’s endpoint:

POST /api/agents HTTP/1.1 Content-Type: application/json Host:  Authorization: Bearer  { "group": { "id": "3ef6bad2-21f2-4a9e-837e-25ee3f24dd20" }, "name": "api test" }

It will return the full definition of the object that was created:

HTTP/1.1 200 OK connection: close date: Mon, 30 Mar 2020 16:50:52 GMT content-type: application/json; charset=utf-8 content-length: 680 {"name":"api test","ownableType":"Agent","created":"2020-03-30T16:50:52.9367519Z","updated":"2020-03-30T16:50:52.9367519Z","createdBy":{"created":"2019-09-05T21:32:21.698821Z","profile":{"name":"Mike Lindenmuth","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"updatedBy":{"created":"2019-09-05T21:32:21.698821Z","profile":{"name":"Mike Lindenmuth","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"group":{"name":"mlindenmuth@j2interactive.com","created":"2019-09-05T21:32:21.698821Z","currentRole":"Admin","id":"3ef6bad2-21f2-4a9e-837e-25ee3f24dd20"},"id":"5a2f36a1-04c9-4db4-b9d9-bb2ec1406bc0"}

Note: Most objects will require a group to be added to as well as several other required properties. See each object definition for what is required. Endpoints will respond with a 400 Bad Request and a message describing what fields are missing.

Update

To update an object make a PUT request to the object’s endpoint with the id of the object:

PUT /api/agents/5a2f36a1-04c9-4db4-b9d9-bb2ec1406bc0 HTTP/1.1 Content-Type: application/json Host:  Authorization: Bearer  { "name": "another name" }

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:

PATCH /api/agents/5a2f36a1-04c9-4db4-b9d9-bb2ec1406bc0 HTTP/1.1 Content-Type: application/json Host:  Authorization: Bearer  [ { "op": "replace", "path": "name", "value": "patched name" } ]

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:

PATCH /api/agents HTTP/1.1 Content-Type: application/json Host:  Authorization: Bearer  [ { "op": "remove", "path": "/8875ce80-f9ca-4508-934f-8c582feb4e1e" }, { "op": "remove", "path": "/1d97f22e-0960-4d40-9fde-f94adbfc5aff" } ]

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:

DELETE /api/agents/5a2f36a1-04c9-4db4-b9d9-bb2ec1406bc0 HTTP/1.1 Content-Type: application/json Host:  Authorization: Bearer

If successful an empty 200 OK response will be returned.

Static IP - Whitelisting

The static IP Addresses to whitelist for the DataBlend API in the US are below:

3.22.2.125

3.20.90.91

The static IP Addresses to whitelist for the DataBlend API in the EU are below:

54.155.0.138

52.50.54.50