HTTP API Tutorial
Dive into the commercetools Composable Commerce HTTP API.
The Composable Commerce HTTP API provides business logic for commerce solutions as web services which you can request using any HTTP client of your choice in any programming language.
A typical application would be a web shop that provides a customizable user interface via HTML and CSS. Those applications perform API calls to carry out actions like searching for Products, putting Products in a Cart or generating Orders.
In this tutorial you will learn the essential basics of the Composable Commerce HTTP API:
- authenticate with OAuth 2.0 to get an
access_token - retrieve Products
Supported clients
The HTTP client used in this tutorial is cURL, but you can use the tool or programming language of your choice to make calls to the Composable Commerce HTTP API.
commercetools also has four SDKs to simplify making API calls. Learn more about commercetools SDKs and follow get started guides for each SDK at:
Prerequisites
We assume that you've completed the getting started guide. We also assume that your Project contains some Products. If your Project is currently empty, you can import the SUNRISE Data to your Project to give you some example Products.
If you are using a commercetools SDK, you can skip Authentication and Preparation as these are automatically performed by the SDK.
Authentication
commercetools Composable Commerce provides authorization via OAuth 2.0 with scopes. The scope enables you to expose the API with limited rights, such as giving smartphone apps the right to view and search for Products but not the ability to change or delete Products.
An OAuth 2.0 token can be generated for your Project with cURL as shown in the cURL cheatsheet.
#!/bin/sh$curl https://clientID:clientSecret@auth.{region}.commercetools.com/oauth/token \-X POST \-d "grant_type=client_credentials&scope=manage_project:demo-project-slug"
{"access_token": "kLhYhqi-XDOsWC_qpOHCkUx07WCYcIyU","token_type": "Bearer","expires_in": 172800,"scope": "manage_project:demo-project-slug"}
The example response means that the token kLhYhqi-XDOsWC_qpOHCkUx07WCYcIyU can be used for the next 172800 seconds (2 days) for the Project identified by the Project key demo-project-slug. This token provides full access to the Project.
To limit the rights to the API, substitute manage_project with one of the listed scopes, such as view_products to only allow read access to the Products.
The token must be included in the HTTP header in every API call. In cURL you can include it using -H 'Authorization: Bearer kLhYhqi-XDOsWC_qpOHCkUx07WCYcIyU'.
Preparation
Set the following environment variables, for example in the current terminal:
projectKey=demo-project-slug # please use your project key insteadtoken=kLhYhqi-XDOsWC_qpOHCkUx07WCYcIyU # please use your token insteadbaseUrl=https://api.{region}.commercetools.com/${projectKey}tokenHeader="Authorization: Bearer ${token}"
Retrieving Products
All Products
To retrieve all Products as described in Query Products, make a GET request to the endpoint ${baseUrl}/products with the token in the HTTP header:
ProductPagedQueryResponse productQueryResult = apiRoot.products().get().executeBlocking().getBody();
{"offset": 0,"count": 5,"total": 5,"results": [{"id": "f3b17f52-9ab1-478f-899c-e3d2d5c74579","version": 2,"productType": {"typeId": "product-type","id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"},"masterData": {"current": {"name": {"en": "SAPPHIRE"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "b6c9c274-3637-41d4-b40e-e4e10a62ef67"}],"slug": {"en": "sapphire1374314429721"},"masterVariant": {"id": 1,"sku": "sku_SAPPHIRE_variant1_1374314429721","prices": [{"value": {"currencyCode": "EUR","centAmount": 2800}}],"images": [{"url": "https://example.com/cli/data/252542005_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"staged": {"name": {"en": "SAPPHIRE"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "b6c9c274-3637-41d4-b40e-e4e10a62ef67"}],"slug": {"en": "sapphire1374314429721"},"masterVariant": {"id": 1,"sku": "sku_SAPPHIRE_variant1_1374314429721","prices": [{"value": {"currencyCode": "EUR","centAmount": 2800}}],"images": [{"url": "https://example.com/cli/data/252542005_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"published": true,"hasStagedChanges": false},"taxCategory": {"typeId": "tax-category","id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"}},{"id": "54e625a3-fb88-4593-82eb-28d1e52a7200","version": 2,"productType": {"typeId": "product-type","id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"},"masterData": {"current": {"name": {"en": "GIRLS HARTBREAK CREW"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "870b3e14-94c1-420e-b830-452a4b0f86a3"}],"slug": {"en": "girls-hartbreak-crew1374314429744"},"masterVariant": {"id": 1,"sku": "sku_GIRLS_HARTBREAK_CREW_variant1_1374314429744","prices": [{"value": {"currencyCode": "EUR","centAmount": 3400}}],"images": [{"url": "https://example.com/cli/data/253234387_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"staged": {"name": {"en": "GIRLS HARTBREAK CREW"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "870b3e14-94c1-420e-b830-452a4b0f86a3"}],"slug": {"en": "girls-hartbreak-crew1374314429744"},"masterVariant": {"id": 1,"sku": "sku_GIRLS_HARTBREAK_CREW_variant1_1374314429744","prices": [{"value": {"currencyCode": "EUR","centAmount": 3400}}],"images": [{"url": "https://example.com/cli/data/253234387_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"published": true,"hasStagedChanges": false},"taxCategory": {"typeId": "tax-category","id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"}},{"id": "11e9c8de-f851-4c3d-bd2b-091edcf3c6df","version": 2,"productType": {"typeId": "product-type","id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"},"masterData": {"current": {"name": {"en": "WB ATHLETIC TANK"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "d312c586-7edf-4d85-a07e-3b3d18c998b1"}],"slug": {"en": "wb-athletic-tank1374314429773"},"masterVariant": {"id": 1,"sku": "sku_WB_ATHLETIC_TANK_variant1_1374314429773","prices": [{"value": {"currencyCode": "EUR","centAmount": 8400}}],"images": [{"url": "https://example.com/cli/data/253265444_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"staged": {"name": {"en": "WB ATHLETIC TANK"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "d312c586-7edf-4d85-a07e-3b3d18c998b1"}],"slug": {"en": "wb-athletic-tank1374314429773"},"masterVariant": {"id": 1,"sku": "sku_WB_ATHLETIC_TANK_variant1_1374314429773","prices": [{"value": {"currencyCode": "EUR","centAmount": 8400}}],"images": [{"url": "https://example.com/cli/data/253265444_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"published": true,"hasStagedChanges": false},"taxCategory": {"typeId": "tax-category","id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"}},{"id": "5becc121-1bbe-45f3-9f67-04208b476b3e","version": 2,"productType": {"typeId": "product-type","id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"},"masterData": {"current": {"name": {"en": "MB SOFTSHELL LINER"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "b6c9c274-3637-41d4-b40e-e4e10a62ef67"}],"slug": {"en": "mb-softshell-liner1374314429797"},"masterVariant": {"id": 1,"sku": "sku_MB_SOFTSHELL_LINER_variant1_1374314429797","prices": [{"value": {"currencyCode": "EUR","centAmount": 10000}}],"images": [{"url": "https://example.com/cli/data/254391631_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"staged": {"name": {"en": "MB SOFTSHELL LINER"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "b6c9c274-3637-41d4-b40e-e4e10a62ef67"}],"slug": {"en": "mb-softshell-liner1374314429797"},"masterVariant": {"id": 1,"sku": "sku_MB_SOFTSHELL_LINER_variant1_1374314429797","prices": [{"value": {"currencyCode": "EUR","centAmount": 10000}}],"images": [{"url": "https://example.com/cli/data/254391631_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"published": true,"hasStagedChanges": false},"taxCategory": {"typeId": "tax-category","id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"}},{"id": "336c316d-7cf2-456d-a178-8e6bfeaede69","version": 2,"productType": {"typeId": "product-type","id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"},"masterData": {"current": {"name": {"en": "MB PREMIUM TECH T"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "870b3e14-94c1-420e-b830-452a4b0f86a3"}],"slug": {"en": "mb-premium-tech-t1374314429824"},"masterVariant": {"id": 1,"sku": "sku_MB_PREMIUM_TECH_T_variant1_1374314429824","prices": [{"value": {"currencyCode": "EUR","centAmount": 10000}}],"images": [{"url": "https://example.com/cli/data/253245821_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"staged": {"name": {"en": "MB PREMIUM TECH T"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "870b3e14-94c1-420e-b830-452a4b0f86a3"}],"slug": {"en": "mb-premium-tech-t1374314429824"},"masterVariant": {"id": 1,"sku": "sku_MB_PREMIUM_TECH_T_variant1_1374314429824","prices": [{"value": {"currencyCode": "EUR","centAmount": 10000}}],"images": [{"url": "https://example.com/cli/data/253245821_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"published": true,"hasStagedChanges": false},"taxCategory": {"typeId": "tax-category","id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"}}]}
Products of a Category
Retrieving all Products at once can be too much load for a single visitor. It makes sense to organize Products into Categories like "long sleeves" or "snowboard equipment." In this example, we want to only load Products in the "long sleeves" category.
First we query all Categories with:
CategoryPagedQueryResponse categoryQueryResult = apiRoot.categories().get().executeBlocking().getBody();
{"offset": 0,"count": 4,"total": 4,"results": [{"id": "b6c9c274-3637-41d4-b40e-e4e10a62ef67","version": 1,"name": {"en": "Snowboard equipment"},"slug": {"en": "snowboard-equipment-b6c9c274-3637-41d4-b40e-e4e10a62ef67"},"ancestors": []},{"id": "d312c586-7edf-4d85-a07e-3b3d18c998b1","version": 1,"name": {"en": "Tank tops"},"slug": {"en": "tank-tops-d312c586-7edf-4d85-a07e-3b3d18c998b1"},"ancestors": []},{"id": "870b3e14-94c1-420e-b830-452a4b0f86a3","version": 1,"name": {"en": "Long sleeves"},"slug": {"en": "long-sleeves-870b3e14-94c1-420e-b830-452a4b0f86a3"},"ancestors": []},{"id": "7a4494b0-674e-4374-b4ab-38396bba6359","version": 1,"name": {"en": "Hats"},"slug": {"en": "hats-7a4494b0-674e-4374-b4ab-38396bba6359"},"ancestors": []}]}
The response shows us that the "long sleeves" Category has the ID 870b3e14-94c1-420e-b830-452a4b0f86a3.
Products are rich objects that can have multiple representations, structured like a tree of objects and arrays.
The first level of the Product object contains the id, key, and the masterData which is of type ProductCatalogData. As the name implies that object holds the Product information that can be in a catalog. ProductCatalogData consists of the two objects current (released data) and staged (draft) of the type ProductData. This object contains the name, categories and description of the Product and also the Variants.
The path to the Category ID is masterData.current.categories[0].id.
Since we know the Category ID and the path in the Product representation, we can filter for it during Product search by using Query Predicates.
cURL helps to urlencode the query for the Category from where=masterData(current(categories(id="870b3e14-94c1-420e-b830-452a4b0f86a3"))) to where=masterData%28current%28categories%28id%3D%22870b3e14-94c1-420e-b830-452a4b0f86a3%22%29%29%29.
final ProductPagedQueryResponse productQuery = apiRoot.products().get().withWhere("masterData(current(categories(id=\"870b3e14-94c1-420e-b830-452a4b0f86a3\")))").executeBlocking().getBody();
{"offset": 0,"count": 2,"total": 2,"results": [{"id": "54e625a3-fb88-4593-82eb-28d1e52a7200","version": 2,"productType": {"typeId": "product-type","id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"},"masterData": {"current": {"name": {"en": "GIRLS HARTBREAK CREW"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "870b3e14-94c1-420e-b830-452a4b0f86a3"}],"slug": {"en": "girls-hartbreak-crew1374314429744"},"masterVariant": {"id": 1,"sku": "sku_GIRLS_HARTBREAK_CREW_variant1_1374314429744","prices": [{"value": {"currencyCode": "EUR","centAmount": 3400}}],"images": [{"url": "https://example.com/cli/data/253234387_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"staged": {"name": {"en": "GIRLS HARTBREAK CREW"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "870b3e14-94c1-420e-b830-452a4b0f86a3"}],"slug": {"en": "girls-hartbreak-crew1374314429744"},"masterVariant": {"id": 1,"sku": "sku_GIRLS_HARTBREAK_CREW_variant1_1374314429744","prices": [{"value": {"currencyCode": "EUR","centAmount": 3400}}],"images": [{"url": "https://example.com/cli/data/253234387_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"published": true,"hasStagedChanges": false},"taxCategory": {"typeId": "tax-category","id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"}},{"id": "336c316d-7cf2-456d-a178-8e6bfeaede69","version": 2,"productType": {"typeId": "product-type","id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"},"masterData": {"current": {"name": {"en": "MB PREMIUM TECH T"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "870b3e14-94c1-420e-b830-452a4b0f86a3"}],"slug": {"en": "mb-premium-tech-t1374314429824"},"masterVariant": {"id": 1,"sku": "sku_MB_PREMIUM_TECH_T_variant1_1374314429824","prices": [{"value": {"currencyCode": "EUR","centAmount": 10000}}],"images": [{"url": "https://example.com/cli/data/253245821_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"staged": {"name": {"en": "MB PREMIUM TECH T"},"description": {"en": "Sample description"},"categories": [{"typeId": "category","id": "870b3e14-94c1-420e-b830-452a4b0f86a3"}],"slug": {"en": "mb-premium-tech-t1374314429824"},"masterVariant": {"id": 1,"sku": "sku_MB_PREMIUM_TECH_T_variant1_1374314429824","prices": [{"value": {"currencyCode": "EUR","centAmount": 10000}}],"images": [{"url": "https://example.com/cli/data/253245821_1.jpg","dimensions": {"w": 1400,"h": 1400}}],"attributes": []},"variants": []},"published": true,"hasStagedChanges": false},"taxCategory": {"typeId": "tax-category","id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"}}]}
You did it! Please check our other tutorials that cover more advanced topics.
For more information on how to use the HTTP API, consult the Composable Commerce API reference.