Data handling
Learn how to pass and retrieve data with our APIs.
REST is a standardised technology that uses JSON to pass structured requests and responses and the HTTP protocol to invoke and select methods.
When providing input you must ensure that the request is well-formed, paying attention to make sure that the JSON request definition adheres to the required case sensitivity which can be different depending on the method or operation you are calling. Please make sure to check, where provided, the sample request and response for each method or operation that you are going to call.
Dates and times
When you are using date/time values in your operation or method calls, you must be aware that our API runs on UTC (Coordinated Universal Time) and returns all dates/times in UTC in ISO 8601 format. To make sure that you are using the correct time you can use the Get server time operation to get the current time of the server our API runs on. This ensures that any time-dependent routines run at the expected time.
Paging through data
The pagination mechanism differs between our v2 and v3 services. You must ensure you use the correct method for the call in use. Learn how to identify which API version a call uses here.
Where API calls have paging support the following paging mechanisms are used:
For v2 service calls
Each call to the API method can return usually up to 1000 records but for some select calls this can be higher, the number of records to fetch is specified by the Select parameter.
To iterate through the record set you use the Select and Skip parameters in tandem. The Skip parameter allows you to specify an offset into the record set. If you want to iterate through the record set by 100 records at at time you should set the Select parameter to 100 and the Skip parameter to 0, which returns records 1 to 100. For subsequent calls you should increment the Skip parameter by your Select parameter value (100) and continue to call until 0 records are returned as this indicates the end of the record set.
For v3 service calls
We use the Seek Pagination (also referred to as Continuation Token or Cursor technique) for pagination with v3 service calls. This technique is simple to use as you only have to state a maximum number of data items to return per call, and optionally set a marker to indicate where the result set should start from.
Passing the pagination parameters
The parameters to control the pagination should be passed on the query string of the URI:
Query String Parameter | Data Type | Comments |
---|---|---|
limit | integer | Optional parameter, with an acceptable range of 0 - 10,000 and a default value of 5,000 |
marker | string | Optional parameter, simply start at the beginning of the data set if omitted |
sort | string | Optional, see each calls documentation to see what sort options they support |
For the initial call to a service that supports pagination you would normally not pass any of the pagination parameters, as you are starting a new data set, and this call will return a set of pagination links which you can then subsequently use to move through the data set.
Pagination Links
Pagination links are helpful URI links and markers to retrieve related data pages when returning a page of data, such as the next page link, previous page link etc… These links can be used to navigate the data set, for API calls use the marker value to move through the data set when passed in the marker query string.
Pagination links are returned by service calls that support pagination as follows:
Field | Type | Mandatory | Notes |
---|---|---|---|
_links | links object | Yes | This is the pagination links to aid data set navigation. |
_items | array | Yes | The returned data items in this page. |
links object:
Field | Type | Mandatory | Notes |
---|---|---|---|
self | linkDetails object | Yes | This is the pagination links to aid data set navigation. |
first | linkDetails object | Yes | The returned data items in this page. |
prev | linkDetails object | No | Only returned if not at the start of the search, as there is no previous page at the beginning of a data set. |
next | linkDetails object | No | Only returned if not at the end of the search, as there is no next page at the end of a data set. |
last | linkDetails object | No | Only returned when it is easy to calculate the last page in the data set, so for dynamic data sets this won't be returned. |
linkDetails object:
Field | Type | Mandatory | Notes |
---|---|---|---|
link | string | Yes | This is the URI to use to access the page of data the link refers to. |
marker | string | Yes | This is the marker value to pass to start a data retrieval at this page. |
Example
In this example the limit is set to 2 and this is the returned response from the first page:
URI: https://api.dotdigital.com/accounts/v1?limit=2&~marketSector=eq::retail
{
"_links": {
"self": {
"link": "https://api.dotdigital.com/accounts/v1/accountId/12456",
"marker": "12456"
},
"first": {
"link": "https://api.dotdigital.com/accounts/v1/accountId/12456",
"marker": "12456"
},
"next": {
"link": "https://api.dotdigital.com/accounts/v1/accountId/12456",
"marker": "12458"
}
},
"_items": [
{
"id": "12456",
"name": "Acme corp.",
"created": "2020-01-01T15:43:10Z",
"updated": "2020-01-15T13:05:00Z",
"marketSector": "retail",
"users": "https://api.dotdigital.com/users/v1?12456"
},
{
"id": "12457",
"name": "Smith inc",
"created": "2019-06-01T15:43:10Z",
"updated": "2019-09-15T13:05:00Z",
"marketSector": "retail",
"users": "https://api.dotdigital.com/users/v1?12457"
}
]
}
Updated 5 months ago