REST API
What is a REST API?
REST (Representational State Transfer)
REST often transfers values to the API as key-value pairs in a URL, similar to using a web browser. However, you may need to make more checks on the responses as these are not as strictly described as in SOAP, and there is no absolute enforcement of the required method arguments and endpoints as there is with SOAP.
Request
The requests you send to the API will need to have the following parts:
URL
https://yourdomain.com/api/rest/v19
The URL includes the Domain, version, and should include the method name.
If the URL contains a reserved character, it must be encoded. Check Percent encoding for more information.
Headers
Authorization header
"Accept" header - set desired response format to "application/json" or application/xml"
"Content-Type" header - set to "application/json" or "application/xml" (POST method only)
Body
(POST method only)
- The content syntax must match the selected content type
The body syntax can be validated at jsonlint.com
Postman example
In the example below, a POST call is being used to get a specified user by email. Please note that application/JSON is required for both the content type and the accept header.
RESTED example
Rested is another common API tool. The POST call below is adding a user to a group. Like in the Postman example above, the Accept and content-type headers are required.
Responses
When using Mapp Engage REST 2.0 web services, you must check the HTTP header that is returned to check the status of your request, as a response status code may only be set in the header, given that some requests do not send a response back to the client in the HTML body. Please be aware that expected responses and examples can be found in the Swagger for each call.
HTTP Code | Message | Action |
---|---|---|
200 | Success | The request succeeded and data on the call is provided in the HTTP body |
204 | Success | Not necessary. Everything went well. |
401 | Unauthorized | Add authorization header. |
403 | Forbidden | Access error (generally invalid login credentials). Validate user type, username, and password. |
404 | Page Not Found | Provide a valid URL. Make sure no "\\" in the URL. |
406 | Not Acceptable | Validate the "Accept" header. |
415 | Unsupported Media Type | Validate the "Content-Type" header. |
417 | Account expired | Try resetting the password or Contact Support |
500 | Database Access Limit Exceeded | Reduce the load to ~10 tps (transactions per second) or Contact Support |
5XX | Internal server error (server could not understand or process request) | In this case, please check this page before escalating to Technical Support. |
Swagger Documentation
Swagger (or OpenAPI) is a method of describing API methods that are exposed via our REST API in a standardized way in a block of JSON. This is similar to how the SOAP API is described using a block of XML in a WSDL file.
You can access Swagger by using the following link with your domain: http://yourdomain.com/apidoc/swagger.json . This domain is the same as the one you use to log in to the Mapp Engage platform.
WADL
Web Application Description Language (WADL) is a machine-readable description of all REST calls. You can find it at
https://yourdomain.com/api/rest/v19?wadl