This article contains information on configuring and using Mimecast’s POST‑based API structure, including request formatting, namespaces, pagination, response handling, and delegated access.
Prerequisites
- You are Developer, using Mimecast APIs to develop integrations with Mimecast.
REST API
The Mimecast API uses a customized variant of the REST model of state transfer. The main distinguishing feature of the Mimecast API style is greater uniformity in calls and responses.
post-REST
We use the POST verb for almost all requests, with the actual function of the request indicated in the URL and most endpoints expecting a JSON body containing details of the request.
Paths and namespaces
All URL paths begin with /api/ followed by a namespace indicating the functional area of the resource and then a function, e.g., /api/domain/create-domain. URL paths never contain identifiers or data.
How to configure requests
Mimecast API function call paths contain no identifiers or data. Such data is instead delivered in the POST body, e.g., rather than:
GET /api/domain?domain=mydomain.comWe use:
POST /api/domain/get-internal-domain
{
"data":[
{
"domain":"mydomain.com"
}
]
}The second term in the request URL path is a namespace representing an area of functionality.
E.g., in the above call, domain indicates the functional area concerned with the management of domain names used in customer email addresses.
The last term in the path (in this case, get-internal-domain) indicates the specific action to be executed.
The request body
Most Mimecast API calls require a content body containing details of the request. This is to be provided as a JSON object containing a field named, data, whose value is a JSON array containing the data items and parameters to be used in the method call.
When multiple items are contained in the data array, the result is equivalent to calling the same endpoint with each item individually, e.g., we could request data for several internal domains as follows:
POST /api/domain/get-internal-domain
{
"data":[
{
"domain":"mydomain.com"
},
{
"domain":"myotherdomain.com"
}
]
}What to expect in responses
Return codes
HTTP response codes from the Mimecast API are strictly indicative of the HTTP call status and not the result of the function itself.
- A 404 means that the request URL does not exist.
- A 200 means that the HTTP call was successfully received and processed. That is, the function was found and executed correctly, however, this does not mean that the requested action was successful.
Function-level success or failure is indicated in the response body content.
Please see API Documentation - API 1.0 Response Codes for a complete list of expected response codes, sub-codes and their definitions.
The response body
All requests except where binary data is returned will return the same base JSON structure. The objects in the body will include the following:
-
dataAn array of objects which contain the data requested, if any has been found. -
metaAn object, which contains a status field that reflects the outcome of the call. It may also contain other call metadata such as:-
paginationAn object, which contains paging information for multi-paged data sets. (If no paging is present, this object may be omitted.) -
failAn array of objects which, if not empty, indicates a call failure. This contains details of the failure, including a "key" field, which indicates the parameter associated with the failure. If no fail object is present, the call is considered a success.
-
E.g., a call to /api/domain/get-internal-domain might return the following:
200 OK
{
"meta": {
"status": 200
},
"data": [
{
"id": "ItMlXSUUouLS7Jz00tSs5PSQWa6OziGmOzM9T",
"domain": "valid.domain.com",
"sendOnly": false,
"local": false,
"inboundType": "any"
}
],
"fail": []
}Or, in a failure case, it might return this:
200 OK
{
"meta": {
"status": 200
},
"data": [],
"fail": [
{
"key": {
"domain": "nonexistent.domain.com"
},
"errors": [
{
"code": "err_domain_not_found",
"message": "Domain not found",
"retryable": false
}
]
}
]
}Pagination
When using an endpoint that returns lists of information, e.g., /api/audit/get-audit-events, responses will include a pagination object, with fields for next and previous pages where relevant, e.g.:
{
"meta": {
"status": 200,
"pagination": {
"pageSize": 25,
"recordStart": 0,
"next": "eNqrVipOTS4tSs.....",
"previous": "eNqrVipOTS4tSs....."
}
},
"data": [
{
...
},..
],
"fail": [
]
}You will only receive a the next field if there is more data to request.
Requesting the next / previous page
To request the next / previous page of data you need to take the token returned from the previous response and add it to the pageToken key in the meta, pagination object of your request, e.g.:
{
"meta": {
"pagination": {
"pageToken": "add token here"
}
},
"data": [
{
...
}
]
}To request the previous page, substitute the next key with previous and use the previous token from the last response.
Setting the page size
The page size relates to the number of results you would like back from the API for a given request. Page sizes can range between 1 and 100. To set the page size add the pageSize key to the meta, pagination object, e.g., to set a page size of 50:
{
"meta": {
"pagination": {
"pageSize": 50,
"pageToken": "add token here if applicable"
}
},
"data": [
{
...
}
]
}Delegate Access
Delegate access relates to making API requests as a user from one Mimecast account for resources on another Mimecast account that the logged in user has permission to access, e.g., an External Administrator.
To access an account you have delegated permission to access, add the accountCode key to the meta object in your request, e.g.:
{
"meta": {
"accountCode": "string"
},
"data": [
{
...
}
]
}You will find the value of an Account Code for a Mimecast account via Account | Account Settings via the Mimecast Administrator Console.
Comments
Please sign in to leave a comment.