Glue documentation update #2394
Conversation
| template: howto-guide-template | ||
| --- | ||
|
|
||
| Convention defines how request and response should look like in order to use something that is agreed in the industry and focus on your application rather than on response format. Using convention allows to users that are not familiar with your API, to start to use it faster as the way how to use it is familiar to them. |
There was a problem hiding this comment.
what do you mean by "in order to use something that is agreed in the industry"?
There was a problem hiding this comment.
Smth that is widely accepted and used by many people in the industry. I mean JSON:API is a convention that is known for a lot of people that use or create APIs
There was a problem hiding this comment.
"What is a Glue API convention?" should be the first page in the conventions section not the last one.
|
|
||
| ## Content negotiation | ||
|
|
||
| Content negotiation is a process that will try to understand in what format request was sent and in what format client is waiting for the response. Also by this we can understand a convention that client want to use. |
There was a problem hiding this comment.
what exactly do you mean by "client" in this document?
There was a problem hiding this comment.
Client like browser
There was a problem hiding this comment.
Or API user. The thing that sends the request and work with the answer later
| @@ -0,0 +1,69 @@ | |||
| --- | |||
| title: Default conventions | |||
There was a problem hiding this comment.
This document title is to generic please provide something more specific.
| template: howto-guide-template | ||
| --- | ||
|
|
||
| Spryker provides some of the [conventions](/docs/scos/dev/glue-api-guides/{{page.version}}/conventions/what-is-api-convention.html) OOTB |
There was a problem hiding this comment.
What does this mean? What the purpose of this sentence? shall the User read the conventions first? before he continuous?
There was a problem hiding this comment.
Just a cross reference if I opened this page first for some reason. Or you mean that sentence is not clear?
|
|
||
| ### JSON:API | ||
|
|
||
| JSON:API is available for usage OOTB in Spryker. In order to use it you need to implement the `Spryker\Glue\GlueJsonApiConventionExtension\Dependency\Plugin\JsonApiResourceInterface` interface in your resource plugin. |
There was a problem hiding this comment.
Why do I need to implement something when it is OOTB? probably you want to say that JSON is default API format in glue communication but if I need to implement something first before I can use it, is not my understanding of OOTB
There was a problem hiding this comment.
Provided an example
| ### JSON:API | ||
|
|
||
| JSON:API is available for usage OOTB in Spryker. In order to use it you need to implement the `Spryker\Glue\GlueJsonApiConventionExtension\Dependency\Plugin\JsonApiResourceInterface` interface in your resource plugin. | ||
| If you need to extend it behaviour or add missing functionality you can add additional plugins in `\Pyz\Glue\GlueJsonApiConvention\GlueJsonApiConventionDependencyProvider`. All provided stacks are using the interfaces from `GlueApplicationExtension` modules and works in the same way as the similar plugins in specific application modules. |
There was a problem hiding this comment.
What does this mean "works in the same way as the similar plugins in specific application modules.
Comment". This information is usless as long to do not understand GlueApplicationExtension please add references or explain.
|
|
||
| JSON:API is available for usage OOTB in Spryker. In order to use it you need to implement the `Spryker\Glue\GlueJsonApiConventionExtension\Dependency\Plugin\JsonApiResourceInterface` interface in your resource plugin. | ||
| If you need to extend it behaviour or add missing functionality you can add additional plugins in `\Pyz\Glue\GlueJsonApiConvention\GlueJsonApiConventionDependencyProvider`. All provided stacks are using the interfaces from `GlueApplicationExtension` modules and works in the same way as the similar plugins in specific application modules. | ||
| Be advised that those plugin stacks are additional stacks and overriding those methods will not disable existing behaviours. If you need to override default behaviour instead, you need to override methods with `Internal` prefix. E.g. `getInternalResponseFormatterPlugins` instead. |
There was a problem hiding this comment.
What is the code example all about? please provide more context why you added this code.
| ## Using API conventions in Spryker | ||
|
|
||
| Spryker is using conventions for its API application. But existing Glue API application using them a bit differently. | ||
| Legacy Glue API is tightly coupled with a [JSON:API](https://jsonapi.org/) convention. So all your endpoints will follow this convention in any case and you have no control over it. |
There was a problem hiding this comment.
You introduce a new phrase here "Legacy Glue" What is it? provide more context or references please.
|
|
||
| Content negotiation is a process that will try to understand in what format request was sent and in what format client is waiting for the response. Also by this we can understand a convention that client want to use. | ||
| Spryker is trying to check if your request uses specific `Content-type` or `Accept` header and if it finds that it's convention specific, e.g. `application/vnd.api+json` for JSON:API it will use it to hijack a request flow and use convention specific formatters and validators first. | ||
| If those headers are not a convention ones, `no convention` approach will be used instead and request and response formats will be selected from same `Content-type` and `Accept` headers. Wildcards can be used in the content negotiation to get any supported format. E.g. if your `Accept` header looks like `application/*`, the first appropriate formatter (most likely `application/json`) will be used to format response. If OOTB formatters are not covering your needs you can always add more by implementing `\Spryker\Glue\GlueApplication\Encoder\Response\ResponseEncoderStrategyInterface` interface. |
There was a problem hiding this comment.
OOTB formatters or JSON only formatter right? do we have reference to that?
Please provide an example how to add an special formatter maybe for XML?
There was a problem hiding this comment.
Provided an example of JSON formatter as an example
|
|
||
| ## How to make your resource convention specific? | ||
|
|
||
| Resources in Glue Storefront API and Glue Backend API can be convention specific. This also means that they cannot be used if convention header is not provided. E.g. if you have a resource that defined as JSON:API convention resource it will not be available with request with `application/json` in the `Content-type` or `Accept` headers. Instead client will get `404` error. |
There was a problem hiding this comment.
New terms please explain or reference
There was a problem hiding this comment.
Glue Storefront API and Glue Backend API
There was a problem hiding this comment.
"convention header" isn't a standard term. while not a standard term, it seems to refer to the use of these custom or vendor-specific media types in headers (Content-Type Header, Accept Header). These headers follow a particular convention or standard, often set by the API developer, to indicate specific processing rules or formats.
|
|
||
| ## Summary | ||
|
|
||
| Convention is a useful way to make your resources interfaces understandable for your clients and also allows you to focus on the implementation itself and forget about formatting data after. A convention will do it for you. |
There was a problem hiding this comment.
Suggested summary: "Using conventions in API design is a powerful approach to make the interfaces more understandable and consistent for clients. It allows developers to focus on core business logic rather than the intricacies of request and response handling, as conventions automate much of the data formatting and standard operations. This leads to more efficient development and a smoother interaction experience for the Glue API users."
| @@ -14,10 +14,10 @@ New Glue projects can create API applications. This is what you need to do in or | |||
|
|
|||
| Because the backend and storefront APIs have different sets of configured services, they also have different settings in Docker and different containers. Ensure your `deploy.yml` file contains the correct setting for `application`. The available options are listed in the following table: | |||
There was a problem hiding this comment.
Why is it now called backend and storefrontAPIs while in "What is a API convention" its called Glue Storefront API and Glue Backend API?
| @@ -305,7 +305,7 @@ Each method in `CustomApiApplication` represents a step in the API application r | |||
|
|
|||
| This application extends `RequestFlowAwareApiApplication`, which means that this API application follows the default Glue workflow. This is beneficial because it lets you make use the most of the Spryker conventions and features that wire into the request flow. | |||
|
|
|||
| If your API uses its own workflow, you can opt for extending `RequestFlowAgnosticApiApplication`. This kind of application has everything—a separate set of application plugins, boot, and run methods—but not the request flow actions. The application that follows the `RequestFlowAgnosticApiApplication` extension is the old Glue storefront API application. It is request-agnostic and creates and follows its own request flow. Here is an example of the application: | |||
| If your API uses its own workflow, you can opt for extending `RequestFlowAgnosticApiApplication`. This kind of application has everything—a separate set of application plugins, boot, and run methods—but not the request flow actions. The application that follows the `RequestFlowAgnosticApiApplication` extension is the Legacy Glue API application. It is request-agnostic and creates and follows its own request flow. Here is an example of the application: | |||
There was a problem hiding this comment.
what is "RequestFlowAgnosticApiApplication" ? class / template/ reference?
please provide useful scenarios where standard request handling mechanisms do not fit the specific needs of the application or where there is a need to integrate with legacy systems.
| template: glue-api-storefront-guide-template | ||
| --- | ||
|
|
||
| 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. | ||
| The Spryker Decoupled Glue API is a set of a few API applications like *Glue Storefront API* and *Glue Backend API* 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. |
There was a problem hiding this comment.
Please call it Spryker Cloud Commerce OS and add a reference to the application description
| * 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. | ||
| * Legacy Glue API application that can be used as a fallback. |
There was a problem hiding this comment.
"...can be used as a fallback." Why? in which cases? please provide context and scenarios. And how can I use it as 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. | ||
| * Legacy Glue API application that can be used as a fallback. | ||
| * New Glue Storefront API that is a replacement for the Legacy Glue and can be used for the same purpose. |
There was a problem hiding this comment.
"Legacy Glue"? do you mean "Legacy Glue API Application"? consistent Terminology is important.
Do we have an explanation somewhere why such a replacement exists and why it only addresses 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. | ||
| * Legacy Glue API application that can be used as a fallback. | ||
| * New Glue Storefront API that is a replacement for the Legacy Glue and can be used for the same purpose. | ||
| * Glue Backend API that can be used to provide API access for the Backoffice functionality directly without any additional RPC calls. |
There was a problem hiding this comment.
Please add a reference to the Backoffice functionality.
do not use any abbreviations without having introduced them first -> RPC (Remote Procedure Call)
Please explain the advantages.
| @@ -92,9 +92,9 @@ For more details about creating a resource, see these documents: | |||
|
|
|||
| ## Resource modules | |||
|
|
|||
| A `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](/docs/scos/dev/back-end-development/client/client.html). It can also communicate with the Spryker Commerce OS (Zed) through RPC calls. | |||
| A `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 Glue Storefront API `Resource` module can communicate with the Storage or Search, for which purpose it implements a [Client](/docs/scos/dev/back-end-development/client/client.html). It can also communicate with the Spryker Commerce OS (Zed) through RPC calls. | |||
There was a problem hiding this comment.
Spryker Commerce OS = Spryker Cloud Commerce OS
RPC = Remote Procedure Calls (RPC)
| --- | ||
|
|
||
| This document describes differences between the backend and storefront code in API modules. | ||
|
|
||
| The Glue infrastructure can build not only the storefront but also backend APIs in the same project. *storefront APIs* inherit the possibilities of the old Spryker Glue implementation in terms of what they can do and what they have access to. For example, storefront APIs can access Storage and Elasticsearch and make RPC Zed calls using Clients. *backend APIs* have direct access to Facades, which lets you create performant backend APIs that you might often need for your projects. | ||
| The Glue infrastructure can build not only the storefront but also backend APIs in the same project. *storefront APIs* inherit the possibilities of the Legacy Spryker Glue implementation in terms of what they can do and what they have access to. For example, storefront APIs can access Storage and Elasticsearch and make RPC Zed calls using Clients. *backend APIs* have direct access to Facades, which lets you create performant backend APIs that you might often need for your projects. |
There was a problem hiding this comment.
"For example, storefront APIs can access Storage and Elasticsearch and make RPC Zed calls using Clients."
have we not switched from Elasticsearch to OpenSearch?
"...that you might often need for your projects." Why? please and examples and references.
| --- | ||
|
|
||
| This document describes differences between the backend and storefront code in API modules. | ||
|
|
||
| The Glue infrastructure can build not only the storefront but also backend APIs in the same project. *storefront APIs* inherit the possibilities of the old Spryker Glue implementation in terms of what they can do and what they have access to. For example, storefront APIs can access Storage and Elasticsearch and make RPC Zed calls using Clients. *backend APIs* have direct access to Facades, which lets you create performant backend APIs that you might often need for your projects. | ||
| The Glue infrastructure can build not only the storefront but also backend APIs in the same project. *storefront APIs* inherit the possibilities of the Legacy Spryker Glue implementation in terms of what they can do and what they have access to. For example, storefront APIs can access Storage and Elasticsearch and make RPC Zed calls using Clients. *backend APIs* have direct access to Facades, which lets you create performant backend APIs that you might often need for your projects. | ||
|
|
||
| The storefront API uses authentication based on the customer, while the backend API is based on the user. |
There was a problem hiding this comment.
"...based on the user." What user? please and more context.
|
|
||
| ``` | ||
|
|
||
| We changed usage of RestResponse and RestRequest with usage of provided transfers. It will require some additional steps and not always easy like in provided example, so we can do it in a different way. |
There was a problem hiding this comment.
"It will require some additional steps and not always easy like in provided example, so we can do it in a different way." Okay? so what does this mean?
|
|
||
| Abstract class must be changed from `Spryker\Glue\Kernel\AbstractPlugin` to `Spryker\Glue\GlueApplication\Plugin\GlueApplication\AbstractResourcePlugin` | ||
|
|
||
| Interface MUST be changed from `Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\ResourceRoutePluginInterface` to `Spryker\Glue\GlueJsonApiConventionExtension\Dependency\Plugin\JsonApiResourceInterface` |
There was a problem hiding this comment.
Why is this "MUST" in capitals and the others not?
|
|
||
| getResourceType()method MUST be renamed to getType() | ||
|
|
||
| getController() method return value MUST be changed from a regular string to FQCN of the new correspondent controller. |
| template: glue-api-storefront-guide-template | ||
| --- | ||
|
|
||
| Currently, Glue includes 3 applications: Legacy Glue API, Glue Storefront API and Glue Backend API. All those applications share a common infrastructure in [GlueApplication module](/docs/scos/dev/glue-api-guides/{{page.version}}/glue-api-infrastructure/glue-application-common-infrastrtructure.html), but also have a few infrastructural differences. |
There was a problem hiding this comment.
"but also have a few infrastructural differences." same, same but different? What and why?
There was a problem hiding this comment.
can you provide a visualisation as and overview ?
| ### Request Flow Agnostic API Application | ||
|
|
||
| Legacy Glue API is an example of `Request Flow Agnostic` application. Its main purpose is to provide an easy way to create your own API application with infrastructure and codebase that you want. | ||
| E.g. you want to create an API application that is a proxy for your 3rd party system. In this case you don't need all those request building, routing and content negotiation that Glue Infrastructure provides you with. You can just do a calls to your system and return response as it is. |
There was a problem hiding this comment.
"You can just do a calls to your system and return response as it is." What?
|
|
||
| ### Request Flow Aware API Application | ||
|
|
||
| On the opposite to `Request Flow Agnostic` is `Request Flow Aware` application. |
There was a problem hiding this comment.
"On the opposite to Request Flow Agnostic is Request Flow Aware application." what?
|
|
||
| In order to create such application, your application class must extend `\Spryker\Glue\GlueApplication\ApiApplication\Type\RequestFlowAwareApiApplication` abstract class. For the full tutorial how to create a new application, please check the [dedicated document](/docs/scos/dev/glue-api-guides/{{page.version}}/create-glue-api-applications.html), because `Request Flow Aware` applications can be also `storefront` and `backend` one. | ||
| The difference is quite easy to understand - `storefront` application has no direct access to DB and can use only `storage` or `search` to fetch data directly, or use RPC call to the backoffice. But the `backend` one has this direct access to DB and also to `Facades` via `DependencyProvider`. | ||
|
|
There was a problem hiding this comment.
There needs to be a lot more to unpack especially in the relationship between Request Flow Agnostic / Request Flow Aware and backend and storefront.
more context and cases. Why should I use what? and how?
| @@ -0,0 +1,263 @@ | |||
| --- | |||
| title: Migration of Legacy Glue API resource to Glue Storefront API infrastructure | |||
There was a problem hiding this comment.
Context is missing
Why should I migrate?
What are the benefits?
we always talk about that Legacy Glue can be fallback but how? and why is this not part of this document?
|
|
||
| ### Adjust processor logic | ||
|
|
||
| The main complexity in the migration of the regular legacy resources would be a old models or “processors“. Income and outcome classes are deprecated and not supported by the new API infrastructure. |
There was a problem hiding this comment.
API infrastructure Glue API infrastructure. consistent Terminology is important
| @@ -12,6 +12,7 @@ redirect_from: | |||
| - /docs/scos/dev/glue-api-guides/202204.0/glue-backend-api/how-to-guides/authentication-and-authorization.html | |||
| - /docs/scos/dev/glue-api-guides/202212.0/decoupled-glue-infrastructure/authentication-and-authorization.html | |||
| - /docs/scos/dev/feature-integration-guides/202311.0/glue-api/glue-api-authentication-integration.html | |||
| - /docs/scos/dev/glue-api-guides/202311.0/authentication-and-authorization.html | |||
| --- | |||
|
|
|||
| For authentication, Spryker implements the OAuth 2.0 mechanism. On the REST API level, it is represented by the Login API. | |||
There was a problem hiding this comment.
please add references to :
- authentication
- Login API
explain what REST API Level is
PR Description
TBD
Checklist