Decoupled Glue APIEdit on GitHub
The Spryker Decoupled Glue API is a set of a few API applications like Glue Storefront API (SAPI) and Glue Backend API (BAPI) of the Spryker Commerce OS. Those applications are built to be used as a contract for accessing Storefront or Backoffice functionality through API. Those applications know how to read and interpret API resources and leverage feature modules that expose existing Spryker functionality.
Existing Glue Applications
Out of the box, Spryker Commerce OS provides three API applications:
- Old Glue API application that can be used as a fallback.
- New Glue Storefront API (SAPI) that is a replacement for the old Glue and can be used for the same purpose.
- Glue Backend API (BAPI) that can be used to provide API access for the Backoffice functionality directly without any additional RPC calls.
Difference between Decoupled Glue Api and the old Glue API
There are a few differences between the current Glue infrastructure (Decoupled Glue API) and the old Glue API.
Possibility to create new API applications
With the current infrastructure, projects can easily create their own API applications that would be completely separated from others. This means that resources can be added only to the new application, and users can’t access them with existing ones.
Decoupling from conventions
Old Glue API was tightly coupled with a JSON:API convention, and all resources have to follow it. With the current infrastructure, resources can use any implemented conventions, create new ones, or even not use any. In this case, the “no convention” approach is used, and a request and response are formatted as a plain JSON. For more details, see Create and change Glue API conventions.
New type of application: Glue Backend API application
With the current setup out of the box, we have an additional Glue Backend API (BAPI) application that is meant to be an API application for our Back Office. This means that with this new application, infrastructure has direct access to Zed facades from BAPI resources. Also, out of the box, we have a separate
/token resource specifically for BAPI that uses Back Office users’ credentials to issue a token for a BAPI resource.
For more details about the difference between SAPI and BAPI, refer to Backend and storefront API module differences.
Current infrastructure lets you switch between different authentication servers. For example, this can be useful if you want to use Auth0 or any other server in addition to implemented servers.
For more details and examples, see Use authentication servers with Glue API.
Glue Storefront API
Glue Backend API
Decoupled Glue API infrastructure is implemented in the same layer of Spryker Commerce OS and called Glue, as the old one. It is responsible for providing API endpoints, processing requests, and communicating with other layers of the OS to retrieve the necessary information. Separate applications are implemented as separate modules—for example,
GlueBackendApiApplication. Each application has its own bootstrapping and a separate virtual host on the Spryker web server (Nginx by default).
Logically, the Glue layer can be divided into separate parts:
GlueApplicationmodule provides a framework for constructing API resources and selecting a proper application. It intercepts all HTTP requests at resource URLs (for example,
http://mysprykershop.com/resource/1), selects a proper application based on a bootstrap file, does content negotiation and selects applicable convention, and executes request flow. Also, this module is used for the fallback to the old Glue API.
- GlueStorefrontApiApplication module: The
GlueStorefrontApiApplicationmodule is used for wiring everything related to the Glue Storefront API resources and route processing. All resources, routes, application plugins, and the rest of the required plugin stacks are wired into this module.
- GlueBackendApiApplication module: The
GlueBackendApiApplicationmodule is used for wiring everything related to the Glue Backend API resources and route processing. All resources, routes, application plugins, and the rest of the required plugin stacks are wired into this module.
- Convention module: Each convention module represents some specific convention and should include all required functionality to format API requests according to this convention. Out of the box, Spryker provides a
GlueJsonApiConventionmodule that represents JSON:API convention.
- Resource modules: A
Resourcemodule implements a separate resource or a set of resources for a specific application. The
Resourcemodule must be dedicated to a specific application but can use different conventions. Such a module handles requests to a particular resource and provides them with responses. In the process of doing so, the module can communicate with the Storage, Search, or Spryker Commerce OS (Zed through RPC call) for the Glue Storefront API application, or it can communicate with a Zed directly through Facades for the Glue Backend API application. The modules do not handle request semantics or rules. Their only task is to provide the necessary data in a
GlueResponseTransferobject. All formatting and processing are done by the convention or selected application module.
- Relationship modules: Such modules represent relationships between two different resources. Their task is to extend the response of one of the resources with data from related resources. Out of the box, these modules are only applicable for resources that are using JSON:API convention.
To be able to process API requests correctly, the
Resource modules need to implement resource plugins that facilitate the routing of requests to the module. Such plugins need to be registered in the application they are related to. Also, plugins must implement a convention resource interface if must implement one.
Glue executes a few steps in order to execute a request:
Application bootstrapping and running
Upon receiving an API request, an API context transfer is created where we set up basic request data like host, path, and method. It can be used to select a required application from the provided applications list. After that,
ApiApplicationProxy is used to bootstrap and run the selected application. If the selected application plugin is the instance of
RequestFlowAgnosticApiApplication, the direct flow is used, and no additional Glue logic is executed. It’s useful if we need to create a simple API application that just returns the result of execution as is. If the application plugin is the instance of
RequestFlowAwareApiApplication, we execute the whole request flow.
Request flow preparation
First, we hydrate
GlueRequestTransfer with data from the
Request object. This includes request body, query params, headers, and attributes.
ContentNegotiator tries to resolve what convention the application must use for this request and updates
GlueRequestTransfer with the request format. The convention is optional, so if it isn’t found, the application uses the requested and accepted format to prepare request and response data.
GlueRequestTransfer and selected or not convention, the application executes
Executing request builders, request validators, and response formatting based on selected convention
At this stage, a bunch of plugin stacks are executed to prepare the request and response. If the convention is selected, the application merges plugins from three different places: default plugins from
GlueApplicationDependencyProvider, plugins from the selected convention, and application-specific plugins. If the convention isn’t found, instead of convention plugins, default flow classes are executed before common and application-specific plugins.
Routing tries to find required resources in two plugin stacks in the selected application dependency provider—for example,
\Pyz\Glue\GlueBackendApiApplication\GlueBackendApiApplicationDependencyProvider::getRouteProviderPlugins(). If no route is found,
MissingResource is selected and executed.
For more details about creating a resource, see these documents:
Resource module is a module that implements a single resource or a set of resources. It is responsible for accepting a request in the form of
GlueRequestTransfer and providing responses in the form of
GlueResponseTransfers. For this purpose, the SAPI
Resource module can communicate with the Storage or Search, for which purpose it implements a Client. It can also communicate with the Spryker Commerce OS (Zed) through RPC calls.
BAPI resources can use direct facade access through the dependency provider and access the database directly.
Resource modules must implement all logic related to processing a request. It is not recommended to have any of the Business Logic, or a part of it, in the GlueApplication or specific application Module. If you need to extend any of the built-in Glue functionality, extending the relevant
Resource module is always safer than infrastructure.
Resource modules have their own naming pattern to follow:
- Storefront resources must use the simple
Apisuffix and resource name in plural—for example,
- Backend resources must use the
BackendApisuffix and resource name in plural—for example,
Recommended module structure:
||Folder for resource controllers. Controllers are used to handle API requests and responses.|
||Bridges to clients/facades from other modules.|
||Folder where all resource processing logic, data mapping code and calls to other clients are located.|
||Contains resource-related configuration.|
||Provides external dependencies.|
||Factory that creates instances.|
Also, a module must contain the transfer definition in
||Contains API transfer definitions.|
The resulting folder structure on the example of the ServicePointsBackendApi Resource module looks as follows:
Glue request structure
|queryFields||Assoc array of query parameters with values.|
|path||Returns the path being requested relative to the executed script.|
|content||Request body content.|
|attributes||Array of attributes from the
|meta||Array of metadata from the
|convention||Selected convention that was selected in
|method||Request “intended” method.|
|parametersString||Normalized query string from the
|httpRequestAttributes||Request parameters from the
|requestUser||Backend user requesting the resource (valid only for Glue Backend API).|
|requestCustomer||Storefront customer requesting the resource (valid only for Glue Storefront API).|
Glue response structure
|httpStatus||Response status code.|
|content||Response body. If the resource sets any data into it, the response body uses it instead of the
|format||Response format—for example,
HTTP status codes
This section provides a list of common HTTP statuses returned by Glue endpoints.
|200||An entity or entities corresponding to the requested resource is/are sent in the response|
|404||Resource not found|
|201||Resource created successfully|
|404||Resource not found|
|200||Resource updated successfully|
|404||Resource not found|
|204||No content (deleted successfully)|
|404||Resource not found|
For date formatting, ISO-8601 date/time format is used. For requests, any time zone is accepted; however, dates are stored and returned in UTC.
- in storage and responses:
|HEADER||SAMPLE VALUE||USED FOR||WHEN NOT PRESENT|
|Accept||application/vnd.api+json||Indicates the data format of the expected API response.||406 Not acceptable|
|Content-Type||application/vnd.api+json; version=1.1||Indicates the request content-type and resource version.||415 Unsupported|
|Accept-Language||de;, en;q=0.5||Indicates the desired language in which the content should be returned.|
|HEADER||SAMPLE VALUE||USED FOR|
|Content-Type||application/vnd.api+json; version=1.1||Response format and resource version.|
|Content-Language||de_DE||Indicates the language in which the content is returned.|
For submitting the form