The REST services below are all be implemented as Enactor Application Processes. These will accept and return Request and Response objects in a similar manner to SOAP web services, this ensures a clean and consistent interface when a client is communicating with the service. However, it is recommended that the implementation of the service does not pass around the request and response – if calls to other processes are needed, the request and response parameters should be unwrapped before they are passed on. This allows the implementation details of the services to be more easily reused by other applications.
REST API Conventions #
In all the services describes below, the following conventions are applied:
Request Method:
POST – This is always a ‘CREATE’ operation. Attempts to POST a resource that already exists should fail. A POST to a collection endpoint should create a new record in the collection. The request body will describe the content of the entity being created – this can be empty which should create a new empty record.
GET – This is always a ‘READ’ operation. GET requests should never modify the data associated with the entity. A request body should not be supplied with a GET request.
PUT – This is a ‘UPDATE/REPLACE’ operation. Attempts to PUT a resource that does not already exist should fail. The request body will fully describe the content the entity should have after the service has completed – If the request body is empty, this implies the entity should be reset to an ’empty’ state.
PATCH – This is a ‘MODIFY’ operation. Attempts to PATCH a resource that does not already exist should fail. A patch request URL should identify the entity, or part of the entity that is being modified. The request body should contain the content for the modification (the new value for the property for example)
DELETE – This is a ‘DELETE’ operation. Attempts to DELETE a resource that does not already exist should fail. A request body should not be supplied with a DELETE request.
Request Headers:
The request headers must include the JSON Web Token, provided by the Identity Service. This will contain the secure data provided from the identity service and will be used to validate authorisation to invoke the service.
Request Parameters:
Unless specified otherwise, Request Parameters contain optional flags that control the behaviour of the service. They should not contain data that relates to the entity being manipulated by the service.
Request Body:
If required, will be a JSON object which describes the content of the entity being manipulated, or the new data to be added to an entity.
In general, the body should not include flags used by the service and should just contain the data for the entity.
Response Status Codes:
See the summary table below for details, but in general 200 (OK) or 204 (No Content) should be returned if the operation completes successfully.
Response Body:
Will be a JSON object which describes the updated/modified entity, or list of entities.
The following table summarises the Response Status Codes and the content of the Response Body for the different request types.
| HTTP Request Method | Operation Type | Response Status Code and Details | |
| Collections (e.g. /baskets) | Items (e.g. /baskets/{id}) | ||
| POST | Create | 201 (Created) – The Location header should include the reference to the new item (e.g. /baskets/{id}) | 404 (Not Found) if {id} doesn’t exist or 409 (Conflict) if {id} does exist. |
| GET | Read | 200 (OK) – Returning the list of baskets in the response body. | 200 (OK) returning the item in the response body or 404 (Not Found) if {id} doesn’t exist |
| PUT | Update/Replace | 405 (Method Not Allowed), unless the service supports replacing the entire collection | 200 (OK) returning the updated item or 204 (No Content) if the update item is not being returned or 404 (Not Found) if {id} doesn’t exist |
| PATCH | Modify | 405 (Method Not Allowed), unless the service supports updating the entire collection | 200 (OK) returning the updated item or 204 (No Content) if the update item is not being returned or 404 (Not Found) if {id} doesn’t exist |
| DELETE | Delete | 405 (Method Not Allowed), unless the service supports deleting the entire collection | 200 (OK) returning the deleted item or 204 (No Content) if the delete item is not being returned or 404 (Not Found) if {id} doesn’t exist |
Access Tokens #
All services will require an Access Token to be supplied when they are invoked. This will be provided by the Enactor Identity Service as a JSON Web Token in the HTTP Headers. It will be used to validate the caller has access to any sensitive data, or to validate that the API being invoked is available to the caller. See this document for details on the Enactor Identity Service.
Enactor will support two tokens can be passed as http headers:
id_token – This token should be used to validate the identity of the caller of the service
site_token – This token should be used to validate the identity of the company on whose behalf the caller is making the request.