This document describes the Rest API provided by Enactor for use with external channels. It is separated out into functional areas, with each section related to a specific service. Note that the final URL use to access the service will be determined based on how the Enactor Web Shop is deployed.
General Implementation Notes #
The REST services below will 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 generally 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. A POST may also be used in cases where an ‘advanced’ query is required, in which case the request body describes the query to perform.
- 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 either:
- A 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.
- A valid Authorisation header that is validated against the Enactor Database to grant access to the service
- If the actor calling the service is a device in the Enactor Estate, then the client device information must be supplied as headers (See https://enactor.atlassian.net/wiki/spaces/CSD/pages/2562228351/Rest+API+General+Notes#Client-Device-Information-Headers )
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 Methods 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 |
Services should also follow common patterns when using the standard HTTP status code where possible:
| HTTP Status Code | Meaning | Example |
|---|---|---|
| 2xx | 2xx status codes always indicate a ‘successful’ call to a service. This may not mean the service performed the requested operation successfully, however it will mean the request was valid and understood. | |
| 200 | OK – The request has been received and a response message describing the result of the service call will be sent. A 200 response should generally have a response body. | After calling GET /baskets, this would indicate the list of baskets is available in the response body |
| 201 | Created – The request has been received and a new resource has been saved/generated. The location the resource can be retrieved from will typically be returned in the Location header of the response. This status code should generally not return a response body. | After calling POST /baskets with a payload, this would indicate the basket has been stored by the Rest API |
| 202 | Accepted – The request has been accepted but has not been completed yet. The Location header of the response should typically provide a url that will allow the status of the request to be examined. This status code should generally not return a response body. | After calling DELETE /order/{orderNumber}/{lineNumber}, this would indicate that the request to cancel the order line has been accepted and will be completed at a later date |
| 204 | No content – The request has been processed and the operation completed normally without producing any response body. | After calling POST /export passing an export request, if the request produced no matching records, a 204 status code will be generated |
| 3xx | 3xx status codes are used to indicate a resource has been moved to another URL. We do not expect to use these codes within the Enactor Rest API | |
| 4xx | 4xx status codes indicate a problem with the client request | |
| 400 | Bad Request – This indicates the request could not be understood by the server. | After calling PUT /basket/{basketId} to replace a basket, if the supplied body is not valid. |
| 401 | Unauthorised – The request has not been processed as the request did not include sufficient authentication/authorisation details, or the details that were provided do not allow access to the requested service or data.This should typically be reserved for authentication errors that are not dependent on the data in the request itself – in other words, this response can be raised without parsing the request body. | After calling any service that requires a valid user/customer. |
| 403 | Forbidden – The request has been understood but the service is refusing to perform the requested operation. This will typically be because the client, while succeeding authentication, has asked to perform some operation they are not authorised for. | |
| 404 | Not Found – The request has been understood, but the service cannot locate the resource the request relates to | After calling GET /baskets/{basketId}/{lineNumber}, this would indicate that either the specified basket could not be found, or the given line number was not found |
| 405 | Method Not Allowed – The request has not been accepted as the specified HTTP method is not appropriate for the requested service | When attempting to call PATCH /basket/{basketId} this would be returned as the service does not support PATCH |
| 409 | Conflict – The request has been understood, but could not be processed as it would result in a conflict | |
| 5xx | 5xx status codes indicate a problem with the server while it was processing a request. This is typically not the fault of request itself, although the request may have triggered the error. | |
| 500 | Internal Server Error – A general error occurred while processing the request. Additional details may be provided if appropriate |