API Customized behavior
How to use commercetools API Extensions and Subscriptions
Headless services are becoming more and more popular. Even though no solution solves all problems, commercetools customized behavior makes many specific use cases possible. Thanks to its multitenant architecture the platform works the same for everyone… except you add custom pieces to the puzzle!
Apart from the custom objects entity, there are two important players that will allow you to customize how the platform acts and reacts to changes: API extensions and subscriptions. The easiest way to understand the difference between both is about timing, while the extension runs right before a creation/change/deletion is persisted, the subscription triggers an event after the action has been persisted in the database.
In order to show how to use them both we are going to look at two different scenarios, implementing them from scratch using Google Cloud Platform (from now referenced as GCP).
API Extension
The platform runs a validation over the payload of the request. If the request is valid the change is prepared and the result is sent to the extension. The logic of the extension function can return three different types of responses:
- OK response, confirming the version received.
- OK with update actions, adding an array of actions to be applied over the version received before it gets persisted.
- ERROR response, preventing the change to be persisted and returning an error to the origin of the request.
If any sent update actions is not valid or the extension responds with an error the action is not persisted and the platform returns an error.
Implementing the API Extension
Imagine you want to check the domain of the email address provided when creating a customer, preventing the creation when is not included in a specific list. Although the platform allows Google Cloud, Azure functions and AWS Lambda functions as trigger. For our example we are going to use Google Cloud Functions (from now on referred as GFC).
STEP 1: Creating the GCF triggered by the extension
On the GCP console go to Functions. Click on Create function and set the name. The default trigger is the one we need (HTTP).
Add the following code to the index.js and then rename the Function to execute to match the one from the code.
Copy the trigger URL for the next step.
STEP 2: Creating the API extension on commercetools
Go to CT’s playground (Europe/America), select Extensions as endpoint and create as command. Enter the draft for the extension:
Notice that we are triggering the extension not only when a customer is created but also when it’s updated.
STEP 3: Create a new customer
Go to the Merchant Center (Europe/America) and try creating new customer using an invalid domain. The UI shows notification error.
For more information on API extensions check the documentation.
Subscription
Let’s say you want to send a welcome e-mail when a new customer is created. The subscription will only be triggered if the creation was successful. The platform is not waiting for any response, so it will only publish to a destination. The destination can be from AWS (SNS or SQS), Azure Service Bus or Google’s Pub/Sub (the one we are going to use for the example).
STEP 1: Creating the Google Cloud Pub/Sub’s topic
On the GCP console go to Pub/Sub. Click on Create topic, set a topic id and create the topic.
We need to give publisher permissions to the platform. Once the topic has been created go to the info panel on the right and click on Add Member on the permissions tab. Enter subscriptions@commercetools-platform.iam.gserviceaccount.com on the new members input and set role for Pub/Sub publisher.
STEP 2: Creating the Google Cloud Function triggered by the Pub/Sub
On the GCP console go to Functions. Click on Create function and set the name. Set the trigger to Pub/Sub and select the topic created previously.
For our example we are going to use the email service Sendgrid, but of course any service would do.
We create a service to send the email using the Sendgrid client:
Now we add a handler to prepare the email and send it using the service:
On the index.js file we join everything together:
Add the package.json with the Sendgrid dependency:
Don’t forget to add the SENDGRID_API_KEY and SENDGRID_FROM_EMAIL environment variables.
STEP 3: Creating the subscription on commercetools
Go to CT’s playground (Europe/America), select Subscriptions as endpoint and create as command. Enter the draft for the subscription:
STEP 4: Create a new customer
Go to the Merchant Center (Europe/America) and try creating new customer using a valid address. Create the customer and check your inbox.
For more information on subscriptions check the documentation.
