REST API Basics
REST stands for “Representational State Transfer”. Basically with a REST API call you are to get a piece of data (called a resource) when you link to a specific URL.
Each URL is called a request while the data sent back to you is called a response.
The Components of a REST API Request
A REST API request consist of 4 components: the url (the endpoint), the HTTP Verbs (the method), the headers and the data (or body).
The url consists of a root-endpoint and a path.
These are the root endpoints of the Xurrent service:
- Production environment global:
https://api.4me.com/v1 - Production environment Australia:
https://api.au.4me.com/v1 - QA environment global:
https://api.4me.qa/v1 - QA environment Australia:
https://api.au.4me.qa/v1 - Demo environment:
https://api.4me-demo.com/v1
The path determines the resource you’re requesting for. For example, you will use the url https://api.4me.com/v1/workflows to access the record type ‘workflows’ in a Xurrent production environment outside Australia.
With the HTTP Verb you specify the type of request you send to the server. You can choose from the types below:
- GET
- POST
- PATCH
- DELETE
These methods provide meaning for the request you’re making. They are used to perform four possible actions: Create, Read, Update and Delete (CRUD).
The HTTP Headers
Each request to the Xurrent REST API must supply two headers to specify your personal access token and to specify the Xurrent account you need access to:
Authorization: Bearer <personal-access-token>X-Xurrent-Account: <accountID>
Access Rights – the Personal Access Token
With a personal access token you tell the Xurrent service who you are and based on your roles in Xurrent and on the access rights that have been specified in your personal access token, you will be able (or not …) to perform the actions on the resources as pecified in your REST API request. Read this topic on personal access tokens in the Xurrent GraphQL training to create and update a personal access token.
The Body
Finally the data (or body) contains information you want to be sent to the server. This option is only used with POST, PATCH or DELETE requests. These data is formatted in JSON (JavaScript Object Notation), a common format for sending and requesting data through a REST API.
Xurrent REST API Documentation
You can find the complete Xurrent REST API library on the Xurrent Developer Website. Please read the general section of the API documentation before you continue with this training.