REST API Guide
- Steve Maher
- David Hunt (Unlicensed)
Obtaining the Authorization 'Bearer Token'
All REST API calls require an authorization token to allow access to the server. This token will be provided to you by Data Makes the Difference during the onboarding process.
Formatting the REST Request
Each REST request must have HTTP headers defined in order for the request to succeed. The description of each REST API details the HTTP headers that are required. This section only provides an overview of these headers.
| Key | Value | Description |
|---|---|---|
| User-Agent | <company identifier> | The exact value here is not important, but it should include something to identify your company and should be consistent across all API calls. This identifier will enable us to help you to debug any issues that you might have. To learn more about this header see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent |
| Accept | application/json | The format of any REST body data returned (only JSON is supported) |
| Authorization | Bearer <your token> | The authorization token given to you by DMTD |
| Accept-Language | <language locale> | The language locale in which to return content |
| Accept-Type | application/json | The format of any provided REST body data (only JSON is supported) |
| X-LearnerId | <the learner id> | The DMTD-supplied identifier that identifies the learner (see below) |
| X-LearnerCode | <the learner code> | A REST-client-supplied identifier that identifies the learner (see below) |
| X-SystemDomain | <the system domain> | (see below) |
| X-UserId | <the user id> | The id of the user to view the learners for (see below) |
| X-UserCode | <the user code> | The code of the user to view the learners for (see below) |
X-UserId and X-UserCode
Either X-UserId or X-UserCode is used to identify one of your users to the REST service. X-UserId is a unique id provided as a result of calling the /1/user - POST API. If this value is to be used, then it must be remembered and returned whenever this user needs to be identified.
Another way to identify users is to assign a unique code to them that is known by your system. This way you do not have to store an additional id to your system. This code must be stable and unique and is provided to the /1/user - POST API call.
Uniqueness
Note that the uniqueness characteristic of the code is unique to all users in DMTD's database. To ensure that this is true, we suggest prepending a static suffix to every code that would uniquely identify your company. For example, if your code is '123ABC', then we would recommend using the code like 'DMTD-123ABC'. If you are unsure if your codes will be unique, you can ask us and we'll let you know. The maximum length of the code is 190 characters.
Consistently Use One Identification Method
Upon design of your application, decided to use either X-UserId or X-UserCode and then use that consistently for all REST API calls. The application should not:
- Switch between using X-UserId and X-UserCode
- Specify both X-UserId and X-UserCode
X-LearnerId and X-LearnerCode
Similar to X-UserId and X-UserCode, the 'X-LearnerId' and 'X-LearnerCode' header is not required on all requests. However, when they are required either of the two may be provided to authenticate the call, both are not simultaneously required.
X-LearnerCode equates the code field that is provided when the learner record is created. This allows you to store a unique value in the code field, for example your primary key, and thus no changes to your data model are required to integrate the REST service.
Consistently Use unsafe-One Identification Method
Upon design of your application, decided to use either X-LearnerId or X-LearnerCode and then use that consistently for all REST API calls. The application should not:
- Switch between using X-LearnerId and X-LearnerCode
- Specify both X-LearnerId and X-LearnerCode
Language Locales
The following language locales are supported:
| Locale | Language |
|---|---|
| en | English |
| es | Spanish |
| fr | French |
| pt | Portuguese |
X-SystemDomain
The following assessments are supported:
| Key | Description |
|---|---|
| vbmapp | The VB-Mapp Assessment |