--- title: "Overview" canonical: "https://red-ant-documentation.refined.site/space/RDD/617971740/Overview" format: markdown --- To perform inbound integrations, RetailOS exposes a public API for external services to push updates to. This API generally aims to follow REST principles to have a consistent interface. With this in mind, it could also be polled for updates for outbound integrations. > Macro (toc) # Quickstart In order to get started with interacting with the RetailOS public API, you will require the following information from Red Ant: - **Swagger interactive UI URL:** URL with endpoint definitions - **Authentication API key header:** e.g. `Authorization: API_KEY ` You will then be able to interact with RetailOS resources. View the [RetailOS SwaggerUI interface](https://digital-store-api-qa.redant.cloud/v2/docs) --- # Transfer protocol and infrastructure - **HTTPS:** RetailOS APIs are designed to accept HTTPS connections. --- # Authentication and security - **API Key**: An Authorization header will be required in the request containing the API key provided by RedAnt. - **IP Whitelisting**: RetailOS can whitelist a set of IP addresses to ensure only expected services are communicating with the API --- # Upserts It is advised to use an idempotent mechanism to push updates to RetailOS. for this reason, most resources in the public API will have a PUT method which behaves as an upsert. The record will be validated to ensure it has the necessary fields required to create, but will update an existing record, should the external id match. For this reason, it is advisable to send full objects to the PUT endpoint with the external id correctly set (in the URL) and the API will update or create. Other HTTP methods will behave conventionally (POST/PUT). --- # Endpoint implementation The following are assumed expectations when sending a request to any of the RetailOS public endpoints. ## Content type RetailOS uses JSON as the content type in its APIs. The following request headers are assumed: ``` Content-Type: application/json Accept: application/json ``` ## HTTP request body RetailOS expects a JSON object as a request body with the fields that match the resource entity model (defined in the Swagger docs). For example, a customer JSON subset request body will be expected to have a shape *similar to*: ``` { "externalCustomerId": "example-customer-id", "title": "Mr", "gender": "Female", "firstName": "Example", "lastName": "Customer", "telephone": "+44 8800000000", "email": "email@example.com", "dob": "01/01/1904", "generalMarketing": false, "thirdPartyMarketing": false, "address": { "city": "", "county": "", "country": "", "address1": "", "address2": "", "postCode": "" } } ``` Please see the up to date resource object model definitions at the [RetailOS SwaggerUI interface](https://digital-store-api-qa.redant.cloud/v2/docs) ## HTTP response body RetailOS aims to have a consistent shape for HTTP responses to aid implementation. Every response will be a JSON object with the result under the property `result` and errors under `error` Example successful response ``` { "error": null, "result": [ { "id": "e92ae5e1-8a9e-4b3e-9c67-d1dfb08f19a2", "queueName": "scv:customer:upsert", "status": "queued", "createdAt": "2020-03-19T10:14:23.707Z", "$$ref": "#/components/schemas/JobQueueMeta/example" } ] } ``` Example unsuccessful response ``` { "error": { "code": "UNAUTHORIZED", "message": "Request unauthorized", "details": {} }, "result": null } ``` Please see the up to date resource object model definitions at the [RetailOS SwaggerUI interface](https://digital-store-api-qa.redant.cloud/v2/docs) ## HTTP response status codes RetailOS will use the HTTP status codes to determine whether an integration was successful/unsuccessful - `2xx` responses are considered successful requests - `4xx` responses are considered bad requests - `5xx` responses should not occur. Contact Red Ant for any 5xx requests. - `404` responses will be returned when a resource is not found, or a route is not found. The response body error message will need to be parsed. ## HTTP response headers RetailOS will set the following response headers to aid debugging. - `X-Ra-Request-Id` Request unique identifier to help trace errors - `X-Ra-Request-Timestamp` ISO timestamp the request was processed on the server - `X-Ra-Server-Version` Server version number --- # Resource entity structure Most RetailOS resources inherit a basic set of fields. These fields are: - `updateSource` - This is a string field to describe the system that has updated the record. Consult RedAnt for the correct value - `createdAt` - ISO Timestamp the record was created - `updatedAt` - ISO Timestamp the record was updated/last modified - `deletedAt` - ISO Timestamp the record was deleted, usually set to `null`. Please check the Swagger API reference for more information. # Error codes You can find detailed information of the error codes returned by the RetailOS API below ## UNAUTHORIZED **HTTP status** 401 Unauthorized **Summary** The RetailOS API endpoints are only accessible to authorized services. If the incoming request does not have valid credentials for any reason, the response error code will be UNAUTHORIZED. **Example** ``` { "error": { "code": "UNAUTHORIZED", "message": "Request unauthorized", "details": {} }, "result": null } ``` **Explanation** This response indicates that the API cannot authorize access for the given request. **Solving the issue** Please check to make sure you have followed the guidelines to correctly authenticate your API requests to RetailOS. ## VALIDATION_ERROR **HTTP status** 400 Bad Request **Summary** When performing CRUD or other actions on a resource, RetailOS may respond with an error code of VALIDATION_ERROR. This is because the request sent to the endpoint does not meet the validation constraints required for a successful request. **Example** ``` { "error": { "code": "VALIDATION_ERROR", "message": "Request failed validation", "details": { "errors": [ "\"title\" is required" ] } }, "result": null } ``` **Explanation** This response indicates that the API failed validation for the request body. In the above example, the field "title" was missing. **Solving the issue** Please check the swagger model definition for the resource [here](https://digital-store-api-qa.redant.cloud/v2/docs) and ensure the request payload matches the schema definition. ## ROUTE_NOT_FOUND **HTTP status** 404 Not Found **Summary** The requested resource could not be found **Example** ``` { "error": { "code": "ROUTE_NOT_FOUND", "message": "Route not found", "details": {} }, "result": null } ``` **Explanation** RetailOS will respond with this error if the URL is invalid and does not correspond to any resources. **Solving the issue** You can find a list of valid resources in the [RetailOS SwaggerUI interface](https://digital-store-api-qa.redant.cloud/v2/docs) ## INTERNAL_SERVER_ERROR **HTTP status** 500 Internal Server Error **Summary** The request to RetailOS failed due to an unexpected problem. **Example** ``` { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Internal Server Error", "details": {} }, "result": null }Copy to clipboardErrorCopied ``` **Explanation** Under normal circumstances, RetailOS should not respond with this error. This response indicates that the API failed to process the request due to an unexpected problem. **Solving the issue** Please contact Red Ant with the date/time of the request, also the request id (found in the response header `X-RA-Request-Id`).