4.1 Basics
The basic concept behind REST (REpresentational State Transfer) is twofold:
- A resource is uniquely identified by a URL.
- Operations are implemented as HTTP requests using a specific method.
By making correctly composed requests to a specific URL using the correct HTTP request method, all operations provided by the API can be performed.
4.1.1 REST URLs
The base URL for the Deployteq Data Model REST API is: https://api.deployteq.net/
Addressing resources in the data model is done by appending the resource names and when necessary the resource ids to the URL. For example, the URL
| https://.../dataextension/pizzas |
|---|
accesses all resources in the pizza table. In this example and all examples below the URL is displayed shortened, but of course all requests need to be done using the complete URL.
The URL
| https://.../dataextension/pizzas/clang_523ae306ee3bf |
|---|
identifies only the pizza with id clang_523ae306ee3bf in the pizzas table.
All resources in tables in the data model automatically receive an id field named clang_id with a generated unique content with the prefix 'clang_'.
It is not possible to assign ids using the API or any other way. A special id is used for the customer table.
Customers are assigned the Deployteq CRM customer id, prefixed with 'clang_'. As an example, the record for the Deployteq customer with customer id 42 is addressed as
| https://.../dataextension/customer/clang_42 |
|---|
When tables are related using a contains relation, they are addressed as subresources within the resource that contains them.
For example
| https://.../dataextension/customer/clang_42/order |
|---|
accesses all orders by the customer with id 42.
| https://.../dataextension/customer/clang_42/order/clang_523ae3385d12c/orderedpizza |
|---|
Taking it one step deeper points to all the pizzas in the order with id clang_523ae3385d12c for the customer with id 42.
When a subresource is requested, the URL must identify all containing resources.
For example, it is not possible to access order data without specifying the customer. The following URL will return an error:
| https://.../dataextension/customer/order/ |
|---|
NB: the customer table is always defined. Regardless of the locale you may be working in in Deployteq, the REST API only recognizes the name 'customer'.
4.1.2. REST methods
The REST API supports the following methods.
The results of the request may vary depending on whether you specify an id in the resource URL.
| HTTP method | withoud id | with id |
|---|---|---|
| GET | return all recources | return identified resource |
| POST | add new resource | invalid request |
| PUT | invalid request | update identified resource |
| DELETE | invalid request | delete identified resource |
4.2 REST responses
4.2.1 Response codes
The REST API responds using the following response codes.
| Code | Message | Meaning |
|---|---|---|
| 200 | Ok | The request completed succesfully |
| 304 | Not Modified | The request returns the same data as a previous GET request with the same properties |
| 400 | Bad request | The request is incorrectly formulated |
| 401 | Unauthorized | The request is not done with sufficient authorization |
| 403 | Forbidden | The request is not allowed access to the response |
| 404 | Not found | The requested resource is not present |
| 405 | Method not allowed | The requested operation is not allowed. |
| 410 | Gone | The requested resource is not present, and no alternative location is known. |
| 423 | Locked | The requested resource is present, but access to the resource is not possible at the time of the request. |
| 500 | Internal server error | An error occurred while processing the request. |
| 501 | Not implemented | The request method is not implemented in the API |
| 503 | Service unavailable | The REST interface is not accessible at the time of the request |
The exact nature of any errors (codes in de 400 range) may depend on the extract request.
4.2.2 Headers
REST responses provide the usual HTTP response headers, and the REST interface may add custom headers.
| Header | Content |
|---|---|
| X-Resource | The URL of the resource that was created or modified |
| X-Deployteq-API-Error | Additional information in case an error was returned |
In case of POST and PUT requests, no data are returned in the response. If the inserted or updated data are required, an additional GET request should be performed to the URL provided in the X-Resource header.
4.2.3 Body
Only in the case of GET requests will a REST response contain data in the response body, in the form of JSON.
The data returned by the REST interface will contain the information described in the data model, and add metadata that can be recognized by the prefix 'clang_' to the field names.
The following metadata may be present in the data:
| Field | Value |
|---|---|
| clang_id | The id of the resource, which may be used in request URLs |
| clang_createdat | The timestamp of creation of the resource |
| clang_createdby | The Deployteq user that created the resource, often the user associated with the API token. |
| clang_modifiedat | The timestamp of the last modification of the resource. |
| clang_modifiedby | The Deployteq user that last modified the resource, often the user associated with the API token. |
Note that you can't set or modify metadata, it is maintained automatically by the API.