Developing an action extension
An action extension is a custom endpoint that can be called from your frontend. It allows you to forward any kind of API calls to backend services, including writing data to it. Especially the latter can't be achieved by a data source extension. The other big differences to a data source extension are:
- An action needs to be triggered manually from the frontend
- Actions can't be configured by studio users
- The data returned by an action isn't automatically available (especially at Server Side Rendering time)
You can think of an action roughly as a controller that's run for you inside the API hub.
1. Implement the action
Actions are categorized into namespaces for clarity. Namespaces are created by nesting objects in the
This action resides in the
star-wars namespace and is named
An action receives 2 parameters:
Requestis a data object that contains selected attributes of the original HTTP (such as
queryholding the URL query parameters) and the session object
ActionContextholds contextual information from the API hub
As the return value, a
Response or a promise returning such, is expected. This response will be passed as the return value to the client. It contains many of the typical response attributes of a standard HTTP response.
We're using the Axios library to perform HTTP requests here. To reproduce this example, you need to add this as a dependency, for example, using
yarn add axios. You can use any HTTP library that works with Node.js, the native Node.js HTTP package, or an SDK library of an API provider.
The action extension in this example receives a URL parameter
search and uses it to find people in the Star Wars API. The result is proxied back to the requesting browser.
2. Use and test the action
Every action is exposed through a URL that follows the schema
/frontastic/action/<namespace>/<name>. So the example action can be reached at
/frontastic/action/star-wars/character. For example, our Frontend component
tsx could look like the below:
You can test this action using a standard HTTP client. It's essential to send the
Accept: application/json header with your request. For example:
For information on the
Commercetools-Frontend-Extension-Version header and the extension runner hostname, see Main development concepts.