Getting Started
macsDS (short for macs data services) is an API that allows you to access mobility related data such as DTC translations, VIN decoding, repair schedule and instructions, and so on.
In this document we will go over some of the conventions of the API which are shared between all the end points it contains. Authentication, error handling and response object structure are all the same no matter which end point you use, so we figured it would be great to see it all in one place.
Security and Authentication
All communication with the macsDS API should be made over HTTPS for security reasons. If you are having timeouts or not getting a response at all from the API, make sure you are using HTTPS and not HTTP.
You would also need to authenticate yourself in order to receive a response from our API using Basic Authorization. Sending a request with no Authorization header or using the wrong credentials will result in a 403 Forbidden error.
You need to include these credentials in the Authorization header. Here is an example:
Authorization: Basic {credentials}
You should in this case replace {credentials} with the credentials found in the dashboard.
Client names in request header
If you integrate our API in order to offer it to your customers [clients], use the request header parameter “clientName” to pass on a client-specific identifier (e.g. the name or a distinct ID) in the request.
That allows a separation of the requests for the purpose of invoicing, usage statistics and analysis:
clientName: your_client_identifier
Response structure
All responses from our API have the same structure, and contain the following fields:
In addition, some other fields may be included when needed. You will not see these fields in the response in case they were not relevant (for example, there will be no error field in a successful response). The additional fields are:
The response code was 200 but the data field is empty. Why?
As a convention, if the request was executed correctly we will respond with HTTP code 200. Correct request means the URL is valid, and all the required argument were provided in the correct format. In some cases the search will have no results and that’s why the data field is empty.
Pagination
Some APIs may return a very large amount of data. For performance reasons, in such cases you will need to request more pages in order to receive the entire data set.
An indication that the dataset is spread over more than one page can be found in the response object. If the totalPages field is larger than 1, then the dataset was too large to serve in one go and was split into multiple pages.
To request a specific page you should send the same request again with additional query parameter: page={pageNumber}.
For example:
/api/v4/dtcs?page=2
The page parameter should be sent in the query regardless of the request method, whether it is a GET or POST request.
Errors
Each error in the response object has these fields:
To see a list of possible errors and how to deal with them, please refer to the troubleshooting table below for general errors, or to the API documentation section for API specific errors.
Troubleshooting
We gathered here a list of common errors that may occur in our API, with suggestions on how to fix them.
If you got an error that is not shown in this table, please refer to the relevan API documentation.