API Extensions and Microservice Layers

Being relatively new, MACH Solutions were able to reconsider and improve many of the ways software services are built and delivered. While some changes, microservices, cloud, and APIs are well known, the technical approach to customization is often ignored. Traditional monoliths leverage plugins, which at first seem like magic, but ultimately lead to pain and uncertainty. Plugins merge code and blur the lines between software and customizations. Plugins make it difficult to debug and optimize the solution as it’s hard to pinpoint the underlying issues. Most importantly, plugins create finger-pointing as multiple companies and teams contribute to the code base. Given these issues, modern headless architecture takes a new and improved approach; the most common is building microservices to handle business logic and coordination. commercetools offers another option with API extensions.

Both API Extensions and API Layers provide huge improvements to the plugins or extensions of traditional monoliths. They offer clear lines between where the platform code ends and the customization code begins. This makes it extremely easy to debug issues and optimize performance, increases system stability, and is a major reason composable architectures have better performance than traditional solutions.

How do you design a Microservices Layer? How do you build an efficient API Extension? What is the best way to extend composable commerce APIs? Let’s answer these questions and explore the differences between API extensions and microservice layers.

API Extensions in commercetools are a tool to help extend and customize the platform’s functionality without altering its core code. They act as synchronous webhooks that can modify or validate data in real time during API calls.

API Extensions follow an event-driven architecture and are triggered by specific actions within commercetools, such as the creation of an order or the update of a cart. They operate synchronously, meaning they process data in real time during an API call before a response is returned. 

API Extensions act as synchronous webhooks that can intercept API calls, perform operations, and potentially modify the request or response. They have access to the object’s data (e.g. cart JSON) and can take specific actions based on that data. Data modifications can be made by returning a list of update actions. Errors can be thrown, which will get passed back to the original code that called the commercetools API. In the case of an error, the original “create” or “update” will not be persisted. The API extension can also just pass success and let the API call proceed as expected.

API Extensions can also be built as serverless functions in the major clouds, AWS, GCP, and Azure. commercetools will call the function directly without having to expose it as an API endpoint.

Pros

• Immediate execution during API calls provides instant feedback
• Can run in serverless functions or commercetools Connect containers reducing infrastructure overhead
• Triggered only when specific events occur, making them efficient
• Applies to every API call, even those from the Merchant Center

Cons

• Can introduce latency to API responses due to the multiple API hops in a chain
• Short timeouts and limited execution time may lead to incomplete processing or lost data
• Not suitable for heavy computations, complex logic, or long-running tasks
• If an API Extension fails, the entire API fails, affecting reliability
• Managing multiple API Extensions is complex, with variable execution order leading to potential bugs
• Limited control over the entire process

A microservice layer acts as an intermediary between your frontend applications and the commercetools API. It’s a separate service that handles requests and responses, allowing you to implement custom business logic.

At the most basic level, these are API services that just sit between the UI and the APIs you plan to use. These can be very similar to a back-end for frontend (BFF), but do not need to be tied to a specific frontend and can be reused across touchpoints. They can be leveraged for a variety of reasons:

• Manage the flow of data
• Implement custom business logic, data transformations, or data aggregation between services
• Handle integrations between systems
• Creating complex business workflows

Pros

• Full customization over request handling, timeouts, and execution flows
• Can be leveraged for complex logic handling, intensive computations, integrations, and workflows
• Container hosting allows for independent scaling based on demand and avoids the performance drawbacks of serverless functions such as cold starts
• Can run in any environment from the cloud to traditional servers

Cons

• The default Merchant Center screens have no way to interact with the service layer, new Custom Applications will need to be built
• Additional costs and effort for hosting, monitoring, and maintaining the service

A good example of when to leverage an API extension would be limiting a maximum quantity in the cart. By default, the cart allows for any line-item quantity, but there may be a business rule that says only a maximum of five is allowed.

This requires immediate feedback to the user which is easy to achieve with an API Extension. The limit is enforced for every API call, so the business rule will be implemented even if a cart is created from the Merchant Center. The rule is applied before the cart is saved, so there is no way for the cart to enter an error state. The API extension does not need to call any other API or do any major work, it can simply take the request, check the line items, and return the necessary response.

By contrast, handling this requirement through a service layer may require multiple API calls to get the cart and update the cart. However, the service layer can override the value and inform the user of the issue in the same call. With an API Extension, you can not combine update actions with errors.

If however, you want to integrate tax calculation, inventory checks, and payment into the checkout process, this is better served by a microservice instead of an API Extension.

A service layer can manage these integrations efficiently, handling retries, error management, and aggregating responses before interacting with commercetools. The order of the calls can be controlled as you would never want to confirm taxes and inventory after collecting payment.

Making these determinations becomes easier with experience and knowledge of the two approaches. However, as general rules, try to leverage API extensions when:

• You have very simple logic that needs to be applied.
• Real-time feedback is required on an interaction including the Merchant Center.
• All necessary data is included in the API call and does not require additional retrieval.
• Having a timeout and retry is acceptable, there is no danger of lost data.

Use a service layer for pretty much all other scenarios, especially when:

• You need to perform complex calculations or data processing.
• Your process involves interacting with various services or data sources.
• You require complete control over the execution flow, error handling, and system behavior.
• You already have a service where the additional logic can be added.
• It’s a critical piece of functionality and lost data will have major impacts, such as for payment processing.

If you need assistance hashing out API extensions and microservice layers as well as designing your composable architecture, Aries Solutions is here to help offer expertise and assistance. Reach out to ask any questions and gain the composable confidence needed for a successful implementation.