CC-37354 Glue RestAPI Migration Phase 1/2

.claude/skills/review/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: review
+description: Run detailed review of the docs changes against the code changes made in suite.
+---
+
+> **Note:** This skill will be removed after all migrations have been completed and documented.
+
+Review my migration documentation changes with extreme scrutiny. The goal is to catch every issue before customers do.
+
+## What to do
+
+1. Get the changed files in this docs branch vs master (`git diff master..HEAD --name-only`).
+2. Get the changed files in the suite repo on the same-named branch vs master as the user for a path if not added as dir.
+3. Do not trust the docs — trust the code.
+4. For every doc change, validate it line-by-line against the actual suite code diff. Every plugin name, every FQCN, every namespace, every method name must match the code exactly.
+5. Console commands in the docs MUST be verified against the suite repo. Check `config/install/docker.yml`, `.github/workflows/ci.yml`, and the actual entrypoints (`vendor/bin/glue` vs `vendor/bin/console`). ```
+
+## Mandatory rules — flag violations as errors
+
+1. Migration guides focus on what to change.
+2. **No Verification sections on per-module migration pages.** Remove curl examples, "how to test", "verify that X works". Projects have their own test harness. 
+
+2. **Cross-cutting must be truly cross-cutting.** A change belongs in cross-cutting ONLY if it is required regardless of which module you migrate first. If it is triggered by migrating a specific module, it belongs in that module's guide — even if it touches a shared file like OauthDependencyProvider or AuthenticationDependencyProvider. Flag any module-specific change sitting in the cross-cutting section.
+
+3. **Console commands must use the correct entrypoint.**
+    - API Platform commands: `docker/sdk cli glue api:generate`, NOT `docker/sdk cli console api:generate`
+    - Glue cache: `docker/sdk cli glue cache:clear`, NOT `docker/sdk cli console cache:clear`
+    - Env var: `GLUE_APPLICATION=GLUE_STOREFRONT` (all caps), never `storefront` (any case is wrong in this context)
+    - The standard post-migration block is:
+      ```
+      docker/sdk cli console transfer:generate
+      docker/sdk cli glue api:generate
+      docker/sdk cli glue cache:clear
+      ```
+
+4. **"Create" vs "update" — say what the code actually does.** If the suite diff shows a new file, the doc must say "create". If it shows a modified file, say "update" or "replace the import". Saying "update" when the file is brand new is wrong.
+
+5. **Relationship plugins — track what stays.** Do not only document removals. Explicitly list plugins that MUST NOT be removed yet because their dependent module has not been migrated. Every migration guide needs a relationship status table.
+
+6. **Internal links must start with `/` and end with `.html`.** This applies to both inline markdown links AND frontmatter `related:` entries.
+
+7. **`last_updated` must be today's date** for every file touched in this PR.
+
+8. **Do not bleed scope.** If a shared dependency provider (e.g., Checkout) has plugins from 5 different modules, only document the plugins relevant to the module being migrated. The rest belongs in their own guides.
+
+9. **FQCNs must be verified against the suite code.** Do not assume the doc has the right namespace — grep the suite repo for every class name mentioned.
+
+10. **Version placeholders `^X.Y.Z` are acceptable** — do not flag these.
+
+## How to report
+
+For every issue found, report:
+- Filename from the project's root and line number, colon separator
+- What is wrong (quote the offending text)
+- What the code actually shows
+- Concrete fix
+
+Be adversarial. Assume every line has a mistake until proven otherwise.

_data/sidebars/dg_dev_sidebar.yml

@@ -876,6 +876,89 @@ entries:
       url: /docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html
     - title: How to migrate to API Platform
       url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform.html
+    - title: Migrate Glue REST API to API Platform
+      url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-glue-api-to-api-platform.html
+      nested:
+      - title: Migrate AgentAuthRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-agentauthrestapi.html
+      - title: Migrate AlternativeProductsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-alternativeproductsrestapi.html
+      - title: Migrate AuthRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-authrestapi.html
+      - title: Migrate CartCodesRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartcodesrestapi.html
+      - title: Migrate CartPermissionGroupsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartpermissiongroupsrestapi.html
+      - title: Migrate CartsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-cartsrestapi.html
+      - title: Migrate CatalogSearchRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-catalogsearchrestapi.html
+      - title: Migrate CategoriesRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-categoriesrestapi.html
+      - title: Migrate CheckoutRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-checkoutrestapi.html
+      - title: Migrate CompaniesRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-companiesrestapi.html
+      - title: Migrate CompanyUsersRestApi and CompanyUserAuthRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-companyusersrestapi.html
+      - title: Migrate ContentProductAbstractListsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-contentproductabstractlistsrestapi.html
+      - title: Migrate CustomersRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customersrestapi.html
+      - title: Migrate CustomerAccessRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-customeraccessrestapi.html
+      - title: Migrate MerchantOpeningHoursRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantopeninghoursrestapi.html
+      - title: Migrate MerchantProductOffersRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantproductoffersrestapi.html
+      - title: Migrate MerchantsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-merchantsrestapi.html
+      - title: Migrate NavigationsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-navigationsrestapi.html
+      - title: Migrate OauthApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-oauthapi.html
+      - title: Migrate OrderPaymentsRestApi and PaymentsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-orderpaymentsrestapi.html
+      - title: Migrate OrdersRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-ordersrestapi.html
+      - title: Migrate ProductAttributesRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productattributesrestapi.html
+      - title: Migrate ProductAvailabilitiesRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productavailabilitiesrestapi.html
+      - title: Migrate ProductBundlesRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productbundlesrestapi.html
+      - title: Migrate ProductImageSetsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productimagesetsrestapi.html
+      - title: Migrate ProductLabelsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productlabelsrestapi.html
+      - title: Migrate ProductMeasurementUnitsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productmeasurementunitsrestapi.html
+      - title: Migrate ProductOfferAvailabilitiesRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferavailabilitiesrestapi.html
+      - title: Migrate ProductOfferPricesRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferpricesrestapi.html
+      - title: Migrate ProductOfferServicePointAvailabilitiesRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productofferservicepointavailabilitiesrestapi.html
+      - title: Migrate ProductOptionsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productoptionsrestapi.html
+      - title: Migrate ProductPricesRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productpricesrestapi.html
+      - title: Migrate ProductReviewsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productreviewsrestapi.html
+      - title: Migrate ProductsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-productsrestapi.html
+      - title: Migrate ProductTaxSetsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-producttaxsetsrestapi.html
+      - title: Migrate QuoteRequestsRestApi and QuoteRequestAgentsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-quoterequestsrestapi.html
+      - title: Migrate SharedCartsRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-sharedcartsrestapi.html
+      - title: Migrate ShipmentTypesRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-shipmenttypesrestapi.html
+      - title: Migrate StoresRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-storesrestapi.html
+      - title: Migrate TaxAppRestApi
+        url: /docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform/migrate-taxapprestapi.html
     - title: Migrate from Auth to SecurityGui module
       url: /docs/dg/dev/upgrade-and-migrate/migrate-from-auth-to-securitygui-module.html
     - title: Migrating from Twig v1 to Twig v3
@@ -1304,6 +1387,10 @@ entries:
           url: /docs/dg/dev/architecture/api-platform/troubleshooting.html
         - title: Sparse fieldsets
           url: /docs/dg/dev/architecture/api-platform/sparse-fieldsets.html
+        - title: Serialization
+          url: /docs/dg/dev/architecture/api-platform/serialization.html
+        - title: Error Handling
+          url: /docs/dg/dev/architecture/api-platform/error-handling.html
         - title: Native API Platform Resources
           url: /docs/dg/dev/architecture/api-platform/native-api-platform-resources.html
 
@@ -1533,6 +1620,8 @@ entries:
       url: /docs/dg/dev/guidelines/data-processing-guidelines.html
     - title: Module configuration convention
       url: /docs/dg/dev/guidelines/module-configuration-convention.html
+    - title: Serializer guidelines
+      url: /docs/dg/dev/guidelines/serializer-guidelines.html
     - title: Security guidelines
       url: /docs/dg/dev/guidelines/security-guidelines.html
 

docs/dg/dev/architecture/api-platform.md

@@ -1,7 +1,7 @@
 ---
 title: API Platform
 description: Spryker's API Platform integration provides schema-based API resource generation with automatic OpenAPI documentation and the integration of the API Platform Bundle.
-last_updated: Feb 26, 2026
+last_updated: Apr 7, 2026
 template: concept-topic-template
 related:
   - title: How to integrate API Platform
@@ -18,6 +18,8 @@ related:
     link: docs/dg/dev/architecture/api-platform/native-api-platform-resources.html
   - title: Sparse Fieldsets
     link: docs/dg/dev/architecture/api-platform/sparse-fieldsets.html
+  - title: Error Handling
+    link: docs/dg/dev/architecture/api-platform/error-handling.html
 ---
 
 Spryker's API Platform integration provides schema-based API resource generation with automatic OpenAPI documentation. This allows you to define your API resources using YAML schemas and automatically generate fully functional API endpoints with validation, pagination, and serialization.
@@ -157,32 +159,68 @@ final class CustomersBackendResource
 
 #### 3. State providers and processors
 
-Detailed information about the API-Platform Provider and Resources can be found on the public docs:
+Spryker provides abstract base classes that simplify Provider and Processor implementation by routing operations to dedicated methods and providing built-in context helpers.
+
+Detailed information about the API-Platform Provider and Processor concepts can be found on the public docs:
 - [API Platform Providers](https://api-platform.com/docs/core/state-providers/)
 - [API Platform Processors](https://api-platform.com/docs/core/state-processors/)
 
 **Provider (read operations):**
 
 ```php
-class CustomerBackendProvider implements ProviderInterface
+class CustomerBackendProvider extends AbstractProvider
 {
-    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
+    public function __construct(
+        private CustomerFacadeInterface $customerFacade,
+    ) {}
+
+    protected function provideItem(): ?object
+    {
+        // GET /customers/{id} — fetch single resource
+        return $this->mapToResource(
+            $this->customerFacade->findCustomerByReference($this->getUriVariables()['customerReference']),
+        );
+    }
+
+    protected function provideCollection(): iterable
     {
-        // Fetch and return data from your business layer
-        return $customerResource;
+        // GET /customers — fetch paginated collection
+        return $this->customerFacade->getCustomerCollection($this->getPagination());
     }
 }
 ```
 
 **Processor (write operations):**
 
 ```php
-class CustomerBackendProcessor implements ProcessorInterface
+class CustomerBackendProcessor extends AbstractProcessor
 {
-    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
+    public function __construct(
+        private CustomerFacadeInterface $customerFacade,
+    ) {}
+
+    protected function processPost(): mixed
+    {
+        // POST /customers — create resource
+        return $this->mapToResource(
+            $this->customerFacade->createCustomer($this->mapToTransfer($this->data)),
+        );
+    }
+
+    protected function processPatch(): mixed
     {
-        // Persist changes through your business layer
-        return $updatedResource;
+        // PATCH /customers/{id} — update resource
+        return $this->mapToResource(
+            $this->customerFacade->updateCustomer($this->mapToTransfer($this->data)),
+        );
+    }
+
+    protected function processDelete(): mixed
+    {
+        // DELETE /customers/{id} — delete resource
+        $this->customerFacade->deleteCustomer($this->getUriVariables()['customerReference']);
+
+        return null;
     }
 }
 ```
@@ -204,7 +242,7 @@ This API is configured to serve the JSON:API format by default, which can be con
 
 ### GlueStorefront API 
 
-Thie API is configured to serve the JSON+LD format by default, which can be configured per project.
+This API is configured to serve the JSON:API format by default, which can be configured per project.
 
 - **API Type:** `storefront`
 - **Application:** Glue
@@ -214,7 +252,7 @@ Thie API is configured to serve the JSON+LD format by default, which can be conf
 ### GlueBackend API
 
 - **API Type:** `backend`
-- **Application:** Zed
+- **Application:** Glue
 - **Base URL:** `http://glue-backend.eu.spryker.local/`
 - **Use cases:** Admin panels, internal tools, ERP integrations
 
@@ -268,40 +306,42 @@ resource:
 
 ### Dependency Injection
 
-API Platform fully integrates with Symfony Dependency Injection:
+API Platform fully integrates with Symfony Dependency Injection. Providers and Processors referenced in resource schema YAML files are automatically discovered and registered as public, autowired services. No manual service registration is needed for standard cases.
+
+If you need custom service configuration (non-standard constructor arguments, decorators, etc.), you can still register services manually in your `ApplicationServices.php`:
 
 ```php
-// config/Zed/ApplicationServices.php
-$services->load('Pyz\\Zed\\', '../../../src/Pyz/Zed/');
+// config/Glue/ApplicationServices.php
+$services->load('Pyz\\Glue\\', '../../../src/Pyz/Glue/');
 ```
 
-Providers and Processors are automatically discovered and can use constructor injection:
+Providers and Processors can use constructor injection to access Zed facades and other services:
 
 ```php
-class CustomerBackofficeProvider implements ProviderInterface
+class CustomerBackendProvider extends AbstractProvider
 {
     public function __construct(
         private CustomerFacadeInterface $customerFacade,
-        private CustomerRepositoryInterface $customerRepository,
     ) {}
 }
 ```
 
 ### Facade integration
 
-Resources can leverage existing Spryker facades:
+Glue layer Providers and Processors access business logic through Zed facades:
 
 ```php
-class CustomerBackendProcessor implements ProcessorInterface
+class CustomerBackendProcessor extends AbstractProcessor
 {
     public function __construct(
         private CustomerFacadeInterface $customerFacade,
     ) {}
 
-    public function process(mixed $data, Operation $operation, ...): mixed
+    protected function processPost(): mixed
     {
-        $customerTransfer = $this->mapToTransfer($data);
+        $customerTransfer = $this->mapToTransfer($this->data);
         $response = $this->customerFacade->createCustomer($customerTransfer);
+
         return $this->mapToResource($response->getCustomerTransfer());
     }
 }
@@ -425,6 +465,20 @@ Response includes both the customer and related addresses in JSON:API format. No
 
 For detailed information, see [Relationships](/docs/dg/dev/architecture/api-platform/relationships.html).
 
+### Error handling
+
+All exceptions are automatically converted to JSON:API error responses with domain-specific error codes. Providers and Processors throw `GlueApiException` with an HTTP status code, a numeric error code, and a message. Validation errors return status `422` with detailed field-level violations.
+
+For detailed information, see [Error Handling](/docs/dg/dev/architecture/api-platform/error-handling.html).
+
+### ETag support
+
+ETag response headers are automatically added when a Provider stores an etag value in the response context. This enables client-side caching and conditional requests.
+
+### Pagination links
+
+Collection responses with pagination automatically include `first`, `last`, `prev`, and `next` links in the JSON:API response. No additional configuration is needed — the links are generated based on the current page, items per page, and total item count returned by the Provider.
+
 ### Sparse fieldsets
 
 Request only the attributes you need using the `fields` query parameter:
@@ -469,7 +523,7 @@ properties:
 | Definition | Schema-based (YAML) | Code-based (PHP) |
 | Documentation | Auto-generated OpenAPI | Manual |
 | Validation | Declarative | Programmatic |
-| Standards | JSON-LD, Hydra | JSON API |
+| Standards | JSON:API, JSON-LD, Hydra | JSON API |
 | Learning curve | Lower | Higher |
 | Flexibility | High | Very high |
 | Use cases | Standard CRUD | Complex business logic |
@@ -491,6 +545,7 @@ For detailed implementation guides:
 - [Native API Platform Resources](/docs/dg/dev/architecture/api-platform/native-api-platform-resources.html) - Using native PHP attributes
 - [CodeBucket Support](/docs/dg/dev/architecture/api-platform/code-buckets.html) - Region-specific resources
 - [Sparse Fieldsets](/docs/dg/dev/architecture/api-platform/sparse-fieldsets.html) - Request only needed attributes
+- [Error Handling](/docs/dg/dev/architecture/api-platform/error-handling.html) - Domain errors, validation, and error codes
 - [Troubleshooting API Platform](/docs/dg/dev/architecture/api-platform/troubleshooting.html) - Common issues
 
 ## Next steps