API’s allow you to build your own UI with DTN data.
Formats
All API’s support both JSON and XML format for responses. Set the Accept header value to the format you prefer to parse. All version 1 API’s use application/json and application/xml for simplicity. See ‘versioning’ down below for Accept headers for version 2 and above of resource requests.
API Keys
DTN has REST web services producing JSON or XML. As with the Widgets, an API key is required to access the services.
API keys can be configured to be authenticated to use different API’s and even different resources within a single API. For example – the Markets API has both Quote and Cash Bid resources. An API key may be configured to access one or the other or both.
The API key MUST be provided for every request. Failure to submit an API key will result in a security error.
When used from a web page and making direct calls to https://api.dtn.com you can pass the API key as apikey query parameter. This helps resolve some CORS issues that may occur if passed as a header from a browser.
When used from a back end service, the preferred method is to pass the key as a header named apikey.
If you don’t get access to a resource you think you should have access to, please contact DTN customer service.
API Calls from Browser or Back-End Server
API’s can be called from either a back end server, or directly from a browser. Because when making API calls directly from a browser, the API key is easy to discover by anybody using the site, there is another layer of security required. Making API calls directly from the browser will require that the web site domain the calls are made from get configured by the DTN customer service team. If your API key is not working from a browser, contact DTN Support.
When making calls directly from the back end server, the domain is not required to be configured. However, just like any username, password combination, the API key should be kept in a secure location and not shared.
Different API key types
When you receive your api keys from DTN customer service, they may be named with one of the following suffixes:
- WEB – this type of key is typically used with the DTN UI Widgets. It can be used to make API calls directly from a browser to the DTN API – but this is not preferred. If not using a UI Widget, the preferred mechanism is to use a SERV key and make the call from the back end service.
- MOB or MOBILE – this type of key is to be used with a DTN UI Widget that is embedded in a Mobile Application.
- SERV – this type of key is to be used on back end servers. This server may be a Web Application server that fetches the data from the DTN API and builds the UI HTML server side.
API Documentation
The API documentation area contains Open API Specification (Swagger UI) documentation for each of the API’s. The Swagger UI is good at showing the URL endpoints, query parameters, headers and responses an API needs and returns, and also gives a good way to give descriptions of the parameters and fields. However, it is not very good at going into some more detailed documentation that is sometimes needed for some of the API’s. This documentation will help delve deeper into API’s.
API Client SDK
In order to help you get up and running quickly and building your own client SDK to consume the DTN services, all our services are documented using Open API Specification (Swagger Specs) and client libraries can be generated. See: Using Open API Specs (Swagger) for details of how you can take advantage of this standard.
Error Handling
All the API’s support HTTP status codes to indicate:
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Created |
| 401 | Unauthorized – please check your API key. |
| 404 | The resource requested is not found. This is different than a search that returns an array and did not find anything because of query parameter filters. |
| 500 | Default and most common HTTP status error message code. Indicates some server error occurred when processing the request. |
Response type
When an error occurs there is a common message construct returned.
{
"messages": [
{
"type": "ValidationError",
"id": "NoMessageId",
"status": 500,
"message": "The number of days requested:120 exceeds the your max allowable based on the products you have for your apikey."
}
],
"meta": {
"type": "Error",
"eventId": "rrt-8634040545409518468-f-gce-11392-89683197-3",
"dateTime": "2018-12-17T21:55:47.214Z"
}
}
Review the Model of the DataDTO in the Open API Specification (Swagger) documentation for details of the meaning of each. That is, on a 500 response you can click on the Model and then drill down into each of the classes within the model for detailed descriptions of each field.
API Versioning
API’s will change over time, new endpoints, new fields returned in responses.
There are 2 types of versions that you may experience with DTN API’s.
- Open API Specification Documentation version – this is a version of the API documentation.
- Endpoint version – and endpoint will only get a new version if the response object is not backward compatible.
Open API Specification Documentation Version
The version of the documentation will be reflected as a point release for small changes such as adding fields to responses, adding query parameters or maybe a small feature endpoint. When there is a larger major change to the API, we may create a whole new specification, meaning there will be a choice of API documentation version on the API specification page.
Endpoint Versioning
When an endpoint becomes backward breaking we will create a new version of that endpoint in order to allow the older version to continue to function and not break existing consumers of the API when the new version becomes available. Typically, only one endpoint becomes backward breaking, so only that endpoint will get a new version. All other endpoints will keep the same version if they are not changing.
A consuming application will define the version they wish to use by supplying the version in the Accept header. Accept headers tell the server what format of a response the consuming application is able to successfully parse. Just like we can define whether the consuming app can parse JSON or XML, it can also define the structure of the response it is able to parse.
For simplicity by default all API’s treat version 1 with an Accept header of application/json or application/xml.The Open API Specification will clearly define the Accept header value to use. If for example an endpoint has a version 2, it will support both application/json and application/vnd.dtn.resource.v2+json indicating that we have a v2 of the resource in json or xml. This will be defined in the Open API Specification.