API Extensions allow you to modify the response of an API call, either by validating the request or by running additional updates.
In this tutorial, we’ll write two small API Extensions: The first one will validate that not more than ten items can be added to the cart. The second one will add a mandatory insurance if any item in the cart is worth $500 or more.
Both examples include downloads for Azure Functions and Google Cloud Functions, for you to be able to start experimenting with API Extensions quickly. However, API Extensions can be run in any way you like as long as they’re accessible via HTTP.
Setting up an API Extension
An API Extension gets called by the commercetools platform during the execution of API calls it has registered for. Let’s register an API Extension that will be called whenever a cart is created, assuming it’s deployed at https://example.org/extension:
As you can see, we’ve specified a single trigger on the cart resource, with a single action.
There are also integrations with some Function-as-a-Service providers. In the following example, we’re specifying a function deployed on Azure that is called whenever a cart is created or updated:
The following steps will assume that you’ve set up an API Extension already. Examples are provided for Azure Functions and Google Cloud Functions, but it should be easy to port them to other frameworks. The code samples work with Google Cloud Functions.
Receiving the API request
We’ll receive an Input that contains the resource after the commercetools platform has executed its business logic. If the API Extension approves the resource (and doesn’t request any changes), it will be persisted as-is. Let’s try it out!
Let’s create a cart:
The API will respond with a cart like this:
Let’s check if our API Extension was actually called! In the logs of our API Extension, we should now see an entry like this:
As we can see, the API Extension got called, and it did receive the cart object. With the exception of the timestamps (which are generated after the API Extension has given it’s approval), the objects are identical.
Validate maximum number of ten items in the cart
Let’s try to do something useful with our API Extension! In the first example, we’ll validate that carts can not reach a state that we won’t allow to order. In our example, every cart containing more than ten line items would be invalid.
First, we’ll have to check the line items in the updated cart that has been given as input to the API extension. If we find more than ten line items in this cart, we’re responding with a 400Bad Request HTTP status code and supply an error message. We’ll also include a known error code - in this case, InvalidInput.
Let’s create a cart with 15 line items that should fail our validation because it is exceeding the limit of 10 line items:
As expected the API responds with the error forwarded from the API Extension!
Some extra fields are added, including the object errorByExtension indicating that the error occurred on an API extension and not inside the commercetools platform. This object contains identifiers for the API Extension that produced the error message helping us to analyze the error.
Add an extra item to the cart
In the second example, we’re looking for a valuable item in the cart - defined as a single item being worth $500 or more - and, if one exists, we’re adding mandatory insurance for it. We’ll also have to remove the insurance if the valuable item was removed from the cart.
To add the mandatory insurance to the cart, we’re sending an AddCustomLineItem update action (which you may recognize from the regular /carts endpoints). To remove the insurance, we’ll send the RemoveCustomLineItem update action.
Let’s try it out! Here, we’re creating a cart with a line item that is worth more than $500:
In the API response, we’ll find that the insurance has been added to the custom line items:
If we remove the line item again, the custom line item is also removed:
We’ve learned how to add API Extensions to the cart API explained on two example implementations: One that validates any changes to the cart, and another one that updates the cart according to it’s current state.
You can learn more about API Extensions in the documentation of the API endpoint.