API extensibility overview
Overview of the concepts related to extending the functionality of your Composable Commerce Project.
commercetools Composable Commerce provides out-of-the-box data structures and behavior that covers the needs of modern commerce solutions. However, your Project may have unique requirements which require these data structures and behavior to be extended.
Composable Commerce provides a range of API extensibility options, allowing you to customize your Project to accommodate various use cases and to enable further integrations. These customization options are Types, Custom Fields, Custom Objects, API Extensions, Subscriptions, and States.
Learn more about how to use API extensibility options with Composable Commerce in our self-paced Extensibility module.
Use cases
We've collected a number of common use cases and the recommended extensibility options you can use to achieve them.
Adding fields to existing resources
Types are similar to Attributes defined by Product Types. They allow you to define extra fields on supported data types within Composable Commerce. For example, to keep track of loyalty information for a Customer, you could create a Type that defines a field for loyaltyPoints.
When you create a Type on a supported data type, the new fields are not automatically attached to all instances of that data type. Instead, you're creating the possibility to define those values when it makes sense to you. To define the values, you use Custom Fields.
Custom Fields refer to the values set for Types on a resource. To reference our earlier example, when creating or updating a Customer, you could use Custom Fields to define values for the newly created loyaltyPoints field.
Adding custom resources
Custom Objects allow you to store namespaced JSON values within your Composable Commerce Project. Any number, string, boolean, array, object, or common API data type value can be saved. This allows you to store and update values used by integrations or other services which interact with your Project.
For example, if you needed to keep information about your individual retail stores, you could create a Custom Object for that use case. Within the Custom Object, you could define the store location, contact details, and any other store-specific information.
Extending behavior
API Extensions are called after the processing of a create or update request of an API call, but before the result is persisted. This makes it useful for synchronous tasks which must be performed before a resource is created or updated. Good use cases for API Extensions are validating the content of a Cart (for example no more than 24 beverage bottles can be ordered at once), calculating custom shipping costs, or adding mandatory items, like insurance, to a Cart.
Subscriptions allow you to receive notifications after a resource is modified. Subscriptions are commonly used to trigger asynchronous background processes. For example, by subscribing to the Customer Created and Customer Email Changed Messages, you can implement a system which sends verification emails when these notifications are received.
Implementing workflows
States allow you to model finite state machines reflecting custom business logic, and are ideal for creating custom workflows. For example, to implement an approval process for new Reviews, you could create the States pending-approval and approved to manage this process.