Learn how to manage resources using the HTTP API.
Introduction
Composable Commerce stores the data of your business entities, for example, products, customers, carts, and orders, as JSON document resources in a Project.
The resources in a Project are isolated from resources in other Projects hosted in the same Region and only authorized clients have access to them.
You can manage the resources in your Project through authorized API clients over HTTP or through the Merchant Center.
Each API request to a resource in your Project must contain the
projectKey that is a unique identifier of your Project.https://api.{region}.commercetools.com/{projectKey}
To manage resources in your Project, the HTTP API provides the typical CRUD (Create, Read, Update, Delete) methods for each type of resource.
Additionally, Composable Commerce offers Search APIs that are optimized for discovery and lookup of a large number of resources of the same type. These and the Product Projection API provide read methods only and their data is kept up to date by background processes running in the platform.
REST
The REST API offers dedicated endpoints of each resource type indicated in the path.
https://api.{region}.commercetools.com/{projectKey}/{resources}
To manage a particular resource, append its unique identifier to the path.
https://api.{region}.commercetools.com/{projectKey}/{resources}/{id}
https://api.{region}.commercetools.com/{projectKey}/{resources}/key={key}
Compliant to REST maturity level 2, the API uses the HTTP verbs
GET, POST, and DELETE to express the CRUD methods:GET https://api.{region}.commercetools.com/{projectKey}/{resources}
POST https://api.{region}.commercetools.com/{projectKey}/{resources}
DELETE https://api.{region}.commercetools.com/{projectKey}/{resources}
The REST API uses
POST requests for updates on resources, instead of PUT or PATCH, to follow the Command Query Responsibility Segregation (CQRS) pattern.
To ensure a good performance of Update operations, the API provides dedicated update actions for the fields of the resources.Resource-specific endpoints
The
{resources} path parameter determines what resource type is targeted, for example:| Endpoint | Accesses |
|---|---|
/customers | Your Customer data. |
/products | All of your Products and Product Variants. |
/orders | Your Order data. |
GET https://api.{region}.commercetools.com/{projectKey}/customers
An HTTP GET request to this URL with the Authorization header returns all your Customer data.
Query parameters
To handle a vast number of resources in our Project efficiently, you can append query parameters to the endpoint to use query features such as filtering, sorting, and paginating the results.
When querying single resources (such as a specified Customer or Product), those query parameters will be ignored as a single JSON object is returned.
GraphQL
The alternative way for managing resources in your project is through GraphQL queries and mutations.
GraphQL fits well if you want to restrict your API responses to exactly what you want to retrieve.
In the RESTful way, you receive the entire resource always and have to extract the fields you are interested with your client application.
Because the filtering happens server-side, GraphQL queries have a slightly longer response time compared to RESTful requests.
All the resources in your Project are managed through the same GraphQL endpoint, REST APIs instead have dedicated endpoints per resource and method.
The GraphQL schema contains the queries and mutations matching the REST API methods.
Because of the similarity in naming, we currently do not provide a detailed API reference documentation for GraphQL queries and mutations.
When you find a REST API method suitable for your use case in the API reference documentation, look for a method with this name in the Merchant Center's GraphQL Explorer to find the corresponding GraphQL query.
In case the name differs significantly between REST and GraphQL, the documentation page contains a hint about the difference.
You can learn how to manage resources through this interface in the GraphQL API reference documentation. The remainder of this document focuses on the REST API.
Read resources
The REST API offers two ways for retrieving resources from your Composable Commerce Project.
If you know the identifier of a resource, you can read it by performing a Get Resource method.
The API then returns the JSON representation of this particular resource in its current state.
You cannot read a previous version of a resource, but you can retrieve a history of changes that have been made to a resource for most of the resource types.
If you don't know the identifier of a resource yet, but you want to retrieve them based on certain criteria, use a Query Resources method.
For such method, the API returns a paged query result, containing the resources that match the criteria you specified.
Get a resource
GET https://api.{region}.commercetools.com/{projectKey}/resources/{ID}
Authorization: Bearer {access_token}
GET https://api.{region}.commercetools.com/{projectKey}/resources/key={key}
Authorization: Bearer {access_token}
Query resources
Query endpoints retrieve multiple resources based on certain criteria specified in a query predicate.
If you omit the query predicate, you can read a collection of all resources of a type with such endpoint.
Query features such as sorting and pagination help you iterating over your collection of resources.
GET https://api.{region}.commercetools.com/{projectKey}/resources
Authorization: Bearer {access_token}
GET https://api.{region}.commercetools.com/{projectKey}/resources?where=fieldName="fieldValue"
Authorization: Bearer {access_token}
Write resources
Writing resources in the HTTP API involves creating, updating, or deleting resources. Each of these operations has its own specific endpoint and requirements. The HTTP API responds to these operations by returning the created, updated, or deleted resource.
Create resources
You create a resource by posting a Resource draft to the Create Resource endpoint of the respective resource type.
The Resource draft is a JSON document in which you include the user-defined fields the created resource should have.
Some fields you must provide, others can be optional.
The API response contains the created Resource with additional fields the platform generated automatically, such as
id, version, createdAt, and lastModifiedAt.For example, to create a new Customer, you post a CustomerDraft to the Create Customer endpoint.
POST https://api.{region}.commercetools.com/{projectKey}/customers
Authorization: Bearer {access_token}
Content-Type: application/json
{
"email" : "johnsmith@example.com",
"password" : "Nf7$kP!2wLz@9qXe"
}
Update resources
To update resources with the API, such as changing a field or adding a new value for a field, you specify with individual update actions which field of the resource you want to update.
Each resource type has its own set of update actions that can be used to modify it. For example, to change a Customer's name, you can use the Set First Name and Set Last Name update actions.
To support optimistic concurrency control, the current
version of the resource to update must be provided together with the update actions.
To update several fields of the resource at the same time, you batch the corresponding update actions in the actions array of the request payload.The resource to update is identified via a path parameter in the URI you append to the POST request to the resource type's endpoint.
POST https://api.{region}.commercetools.com/{projectKey}/customers/{customerID}
Authorization: Bearer {access_token}
Content-Type: application/json
{
"version": 1,
"actions": [
{
"action": "setFirstName",
"firstName": "John"
},
{
"action": "setLastName",
"lastName": "Smith"
}
]
}
Optional fields can be unset by sending an update action with an empty value.
Delete resources
To delete a resource with the API, make a DELETE request to the resource's endpoint and append the resource identifier as path parameter in the URI.
You must include the current
version of the resource to delete as query parameter.DELETE https://api.{region}.commercetools.com/{projectKey}/customers/{customerID}?version=1
Authorization: Bearer {access_token}
Personal data associated with a resource can be deleted in accordance with GDPR with an optional
dataErasure parameter.