HTTP API Tutorial
Dive into the commercetools platform HTTP API.
The commercetools platform HTTP API provides business logic for e-commerce solutions as Web services which you can request by any HTTP client of your choice in any programming language you like.
A typical application would be a Web Shop providing a full customizable user interface via HTML and CSS. Those applications do HTTP calls to the commercetools platform to perform actions like searching for products, putting products in a cart or generating orders.
In this tutorial you will learn the most essential basics of the commercetools platform HTTP API
- to authenticate with OAuth 2.0 to get an
access_token - to retrieve products
Supported clients
commercetools supports clients in three different languages to help you connect with the HTTP APIs:
Java clientthat comes with the JVM SDKPHP clientcontained in the PHP SDKNode.js clientprovided by the JavaScript SDK
The HTTP client used in this tutorial is cURL, but you can use one of your choice instead.
Prerequisites
We assume that you've completed the Getting Started Tutorial to get your API keys that allow you accessing the commercetools platform. We also assume that the commercetools platform project you'll use for this tutorial contains some products. When creating new commercetools platform projects in the Merchant Center you'll be asked if you want to fill your project with some example product data.
Authentication
The commercetools platform 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 possibility to change or delete products.
How to generate an OAuth 2.0 token for your project with cURL is 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 with full access.
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 has to be part of the HTTP headers in every shop related request. In cURL this is done by -H 'Authorization: Bearer kLhYhqi-XDOsWC_qpOHCkUx07WCYcIyU' as command-line argument.
Preparation
Please 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 you just need to make a GET request to the endpoint ${baseUrl}/products with the token in the HTTP header:
final ProductQuery productQuery = ProductQuery.of();return client.execute(productQuery);
{"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 for an entire shop can be too much load for a shop visitor. It makes sense to organize products into categories like 'long sleeves' or 'snowboard equipment'. Now we want to load just 'long sleeves'. First we query for all categories with:
final CategoryQuery categoryQuery = CategoryQuery.of();return client.execute(categoryQuery);
{"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.
The products are rich objects that can have multiple representations. You can find those on the product documentation page and think of it as a tree of structured objects and arrays. On the first level of the product objects are the ID, the name displayed in the Merchant Center and the masterData which is of type ProductCatalogData. As the name implies that object holds the product information that can be in a catalog. The ProductCatalogData consists of the two objects current (released data) and staged (draft) of the type ProductData. This object finally contains the name of the product for the customer, the description, the variants, the categories array and much more.
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 the Query Predicates.
cURL helps to urlencode the query for the category 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 ProductQuery productQuery = ProductQuery.of().plusPredicates(m -> m.masterData().current().categories().id().is(categoryId));return client.execute(productQuery);
{"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! We will continue to make tutorials for more advanced topics.
For more information on how to develop with the commercetools platform consult the developer resources.