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

200SuccessThe 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