Overview
Aurora v2 API is a collection of json based REST API's. Full details about each API's request and response can be found in this API Reference document, where you can also prepare and make test requests to the Aurora Demo data.
Get some help from AI
Why not try out Aurora's new AI Training Packages specifically designed to allow you to train your AI of choice in how to interact with the Aurora APIs.
Get more information here and enjoy gaining insight into how Aurora works instantly!
Getting started
All endpoints share a single common root URL, as follows:
https://[client environment name].[account code].myauroraapi.com/v2/[orders/stock/products/etc]
The 'client environment name' is a unique value that represents each of the Stores you have hosted by Aurora Commerce.
To find out what values you should be using here, please contact your internal API management team or your Account Manager.
For a full list of the APIs and URLs available on your Test and Live Stores please contact your account manager.
Examples of all the APIs using Aurora Demo can be found in the endpoint documentation found to the left of this article.
Simply select an endpoint and click the "Try Me" button.
API Access
To access your API's you need to be able to authorise against them. Using the api credentials manager create a client ID and client secret that you can then use against the authorisation endpoint to receive an authorisation token.
The authorisation URL is located at https://[client environment name].[account code].myauroraapi.com/v2/access_token
A curl request to get an access token for Aurora Demo APIs would look like this:
curl --location 'https://aurorademo-public.dev.myauroraapi.com/v2/access_token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic YXVyb3JhY29tbWVyY2U6dGVzdA==' \
--data-urlencode 'client_id=56b4d07b28b8b7c7fa4e10dbda31420c' \
--data-urlencode 'client_secret=64b2454c5707d7e34e393d1defb71de93d19b51bd2ba8fdc99c1f35d59f408a3' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scopes=*'
Response
{
"token_type": "Bearer",
"expires_in": 86400,
"access_token": "[token]"
}
You will then receive a bearer token that can be used in future requests to the required API.
This token is sent with all requests to allow access. Requests without a token, or with a token that doesn't have the correct permissions will be denied.
Once the token expires a new token will have to be requested.
API Reference
Give it a Try!
This reference material uses the Open API specification to create an interface for testing requests. The API references use the Aurora Demo API and data to power its "Try Me" responses.
That right! All responses returned by the 'Try Me" future are powered by real-time and genuine API endpoints.
Remember! It get's reset!
Give it a try on Aurora Demo. A change on the Aurora Demo website will be viewable via these APIs and vice versa, but these changes are reset nightly and so after 24 hours, you will and any changes have reverted to the previous 'clean' state.
Demo Authorisation Token
Before using the API Reference's "Try Me" features to test requests and see responses you are required to have a token.
To request a token please contact your internal API management team or your Account Manager.
You can still use the API Reference without a token to view available parameters and the expected response formats. This only prevents you from using the "Try Me" feature without requesting an access token from Aurora Demo.
Send test requests
Once you have the token you can then test the services via the readme gui.
- First go to the service and endpoint you wish to test.
- Click on the user icon next to the orange "Try it" button.
- Paste the token in the field.
- Set any additional parameters you wish to use.
- Press "Try it"
- Your response will appear in the right hand side of the interface.
Example code
Each endpoint within the reference section shows some basic code examples in a variety of languages. These can be used as a starting point for your own code.
Curl
Curl requests can also be made directly to the Aurora demo endpoints.
curl --request GET \
--url 'https://aurorademo-public.dev.myauroraapi.com/v2/orders?page=1&pageSize=30' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [token here]'
Common functionality
All the APIs share some common functionality in how the requests and responses behave. Please find a brief overview of these to help give you an insight into what to expect from the Aurora V2 API.
Responses
All responses have the same common format that provides standardised information in the response.
| Parameter Name | Type | Description |
|---|---|---|
| requestId | string | An identifier that can be used to trace a single HTTP request from a client to a service or several services. This allows the Aurora support team to inspect particular requests in logs, as well as for distributed tracing of requests. |
| version | string | The version number. A string because it will be SemVer e.g. 1.2.11 |
| timestamp | string | An ISO 8601 formatted date string representing the date and time that the server received the request e.g. 2004-02-12T15:19:21+00:00 |
| payload | object | An arbitrary data structure that is populated by the return data of the service that has been called. Could be a NULL value if the service returns no content, but it the "payload" field will always be present in the response. |
| notices | null/array | Populated when there are additional pieces of information that would be useful for the API client to know about. Deprecated fields included in the request or the sunsetting of an API version, for example. Field is not present in response when there are no notices |
Responses that return a collection of items will have a payload object in this format.
| Parameter Name | Type | Description |
|---|---|---|
| payload.items | array | An array of arbitrary data structures returned by the service. Each element in the array represents a single item in the collection. |
| payload.paging | object | A data structure that contains information required by the client to navigate through the collection |
| payload.paging.currentPage | int | The page of the collection that items have been returned for. |
| payload.paging.itemsPerPage | int | The number of items per page that should be returned to the client. |
| payload.paging.totalItems | int | The total number of items returned by the search when paging parameters are not taken into account. |
| payload.paging.next | null/string | A URL to the API endpoint the client can call to fetch the next page of results in the collection. NULL when there is no next page available |
| payload.paging.previous | null/string | A URL to the API endpoint the client can call to fetch the previous page of results in the collection. NULL when there is no previous page available |
Responses that return a single item e.g. a request for order id 1, /orders/1 will have a payload in this format.
| Parameter Name | Type | Description |
|---|---|---|
| payload.order | array | A single array of order data. |
Example response for a collection of items
{
"requestId": "3njPTwYFzqm2jNNNNvzqrW",
"version": "1.0.0",
"timestamp": "2020-10-02T01:47:30+0000",
"notices": [
"Field 'id' is to be deprecated. Please update your client to use 'orderId' instead.",
"This API is being sunset on 2021-01-01. Please upgrade your client to v2"
],
"payload": {
"items": [
{
"id": 1234,
...
},
{
"id": 4567,
...
}
],
"paging": {
"currentPage": 2,
"itemsPerPage": 30,
"totalItems": 250,
"previous": "/orders?page=1",
"next": "/orders?page=3"
},
}
}
Example response for a single item
{
"requestId": "3njPTwYFzqm2jNNNNvzqrW",
"version": "1.0.0",
"timestamp": "2020-10-02T01:47:30+0000",
"notices": [
"Field 'id' is to be deprecated. Please update your client to use 'orderId' instead.",
"This API is being sunset on 2021-01-01. Please upgrade your client to v2"
],
"payload": {
"order": [
"id": 1234,
...
]
}
}
Missing/Not found
A request for a single item that does not exist e.g. /order/9999999999 will return a 404 response.
{
"requestId": "975UtvAdM9u1FDS5J4N813",
"helpDocumentation": [],
"problem": [],
"status": 404,
"type": "about:blank",
"title": "Not Found"
}
A request for a collection of items e.g. a search /orders?orderStatus=new, that has no results will return a 200 response with an empty payload section and a paging object that has paging.totalItems = 0.
Sometimes you will find the need to set contextual parameters on your request. These parameters, do not filter the results but change the nature of the response format/data, will return a 404 (as shown above) for values that do not exist. This might include currencies or languages that do not exist. This is to indicate clearly that the value request simply does not exist and no matter how many times you request the data, you are unlikely to ever get data.
Missing Contextual Values
If you are receiving unexpected 404s for your request, e.g. you request the French translations but get a 404, then you should contact your internal Aurora management team to establish why this data (in this example the French language) is not available.
Typically, Aurora Commerce cannot help you with such issues.
Validation
If there is a validation error when performing a request an error is sent back in the response. This is in the form of a status 400 bad request json problem.
A request using an invalid parameter would return a problem response with a status of 400. The response would explain what the issue is and how to fix it.
e.g. /orders?incorrect=abc
{
"requestId": "Q36vdtV4maTZbeXr4HxgED",
"helpDocumentation": {
"description": "Orders API Documentation",
"url": "https://docs.auroracommerce.com/docs/aurora-v2-api-guide"
},
"problem": {
"incorrect": [
"This field was not expected."
]
},
"status": 400,
"type": "validation_error",
"title": "Validation Error"
}