REST API Endpoint
Test your EndPoint
Before you create your first REST API call, make sure that you can reach the endpoint of the Xurrent demo environment with CURL or whatever developer tool you are using. You don’t need to include a header for the personal access token or to specify an account to test the endpoint.
Exercise:
Can you create a CURL command to test the REST API endpoint of the Xurrent demo environment? What response do you receive?
This is the CURL command:
curl -i "https://api.4me-demo.com/v1"
When you excute this REST API call you should receive a HTTP 200 OK response with a body of 2 characters {}.
REST API Error Handling
In the previous exercise you received a HTTP 200 OK response. When you create an integration based on REST API, you should always check the HTTP Status Codes in return of the HTTP POST request (and it should return status code 200 OK - Success!). When you receive a HTTP status code different from 200 then you have probably one of the following issues:
- Server problems (5xx HTTP codes, 1xxx WebSocket codes)
- Client problems like rate-limited, unauthorized, etc. (4xx HTTP codes).
REST API Rate Limiting
In the list with HTTP Status Codes there is the important 429 Too Many Requests - Rate Limit Exceeded status code. All cloud API providers have to protect and preserve the available resources for the users by setting rate limits on APIs. And all integrations with the Xurrent service should respond to rate limiting conditions by evaluating the Retry-After header in the 429 response that contains the number of seconds the integration should wait before retrying the same request. See here for a detailed description of the Rate Limiting.
CURL Command Syntax
When you have created a personal access token for Howard Tanner you are ready now for some exercises. Let’s have a look at the syntax of a full REST API command in CURL.
You can include the two mandatory headers with the Curl -H option.
curl -X <HTTP Verb> -i -H "Authorization: Bearer <personal-token>" -H "X-Xurrent-Account: <accountID>" "https://api.4me-demo.com/v1/<path>"
When copying a CURL command from an example in this training, be sure to replace <personal-token> with Howard Tanner’s actual peronal access token.
Please note also the following:
-i: Interactive mode from CURL will show additional information like the response headers.