Migrate project-level Glue REST API customizations to API Platform

This document describes how to migrate project-level (src/Pyz/) Glue REST API customizations to the new API Platform architecture. It covers cross-cutting concerns that apply regardless of which individual modules you migrate.

Prerequisites

Before starting, make sure you have completed:

• How to integrate API Platform
• How to integrate API Platform Security

Overview of changes

The migration from Glue REST API to API Platform introduces these cross-cutting changes at the project level:

1. GlueApplicationDependencyProvider — remove migrated route plugins and relationship plugins.
2. GlueStorefrontApiApplicationDependencyProvider — remove migrated storefront resource plugins.
3. GlueBackendApiApplicationDependencyProvider — remove migrated backend resource plugins.
4. Obsolete Pyz RestApi modules — delete old Pyz overrides and create replacement modules.
5. Plugin interface migration — adapt custom plugin implementations to new extension interfaces.
6. Custom endpoint migration — migrate project-specific REST API endpoints to API Platform.

1. Clean up GlueApplicationDependencyProvider

The file src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php is the central wiring point for all legacy Glue REST API routes and relationships. After migrating modules to API Platform, remove the plugins that are no longer needed.

Remove migrated resource route plugins

Remove the following plugins from the getResourceRoutePlugins() method:

Authentication and tokens:

Products:

Carts:

Customers:

Orders and checkout:

Company:

Catalog, categories, navigation, and content:

Merchants:

Quote requests (B2B):

Shipments and stores:

Multi-factor authentication:

Validators:

Remove migrated relationship plugins

Remove the following plugins from the getResourceRelationshipPlugins() method.

Product relationships:

Catalog search relationships:

Customer relationships:

Cart relationships:

Checkout data relationships:

Order relationships:

Company relationships:

Merchant relationships:

Navigation and content relationships:

Also remove unused config class references

Remove any remaining use statements for old RestApi config classes that were referenced in relationship registrations:

• Spryker\Glue\CatalogSearchRestApi\CatalogSearchRestApiConfig
• Spryker\Glue\CheckoutRestApi\CheckoutRestApiConfig
• Spryker\Glue\ContentProductAbstractListsRestApi\ContentProductAbstractListsRestApiConfig
• Spryker\Glue\CustomersRestApi\CustomersRestApiConfig
• Spryker\Glue\DiscountPromotionsRestApi\DiscountPromotionsRestApiConfig
• Spryker\Glue\MerchantsRestApi\MerchantsRestApiConfig
• Spryker\Glue\MerchantProductOffersRestApi\MerchantProductOffersRestApiConfig
• Spryker\Glue\NavigationsRestApi\NavigationsRestApiConfig
• Spryker\Glue\OrdersRestApi\OrdersRestApiConfig
• Spryker\Glue\ProductMeasurementUnitsRestApi\ProductMeasurementUnitsRestApiConfig

2. Clean up GlueStorefrontApiApplicationDependencyProvider

In src/Pyz/Glue/GlueStorefrontApiApplication/GlueStorefrontApiApplicationDependencyProvider.php, remove the following plugins.

From getResourcePlugins():

From getRequestAfterRoutingValidatorPlugins():

3. Clean up GlueBackendApiApplicationDependencyProvider

In src/Pyz/Glue/GlueBackendApiApplication/GlueBackendApiApplicationDependencyProvider.php, remove the following plugins from getResourcePlugins():

4. Delete obsolete Pyz RestApi modules and create replacements

The following table shows old Pyz RestApi modules that must be deleted and the new Pyz modules that replace them.

CartsRestApi to Cart

Delete: src/Pyz/CartsRestApi/ (entire directory)

This module contained:

• Pyz\Glue\CartsRestApi\CartsRestApiConfig — guest cart resource configuration, eager relationship settings
• Pyz\Zed\CartsRestApi\CartsRestApiConfig — quote creation settings during quote merging
• Pyz\Zed\CartsRestApi\CartsRestApiDependencyProvider — Zed-side cart quote expander and mapper plugins

Create: src/Pyz/Cart/src/Pyz/Glue/Cart/CartDependencyProvider.php

The new module registers item request expanders, item response mappers, and cart resource mappers through the new CartExtension plugin interfaces. See Migrate CartsRestApi for the full file content.

CartCodesRestApi to CartCode

Delete: src/Pyz/CartCodesRestApi/ (entire directory)

This module contained:

• Pyz\Glue\CartCodesRestApi\CartCodesRestApiDependencyProvider — discount promotion mapper plugin

Create: src/Pyz/CartCode/src/Pyz/Glue/CartCode/CartCodeDependencyProvider.php

The new module registers cart resource mapper plugins. See Migrate CartCodesRestApi for the full file content.

CheckoutRestApi to Checkout

Delete: src/Pyz/CheckoutRestApi/ (entire directory)

This module contained:

• Pyz\Glue\CheckoutRestApi\CheckoutRestApiDependencyProvider — checkout request validators, response mappers, request expanders
• Pyz\Glue\CheckoutRestApi\CheckoutRestApiConfig — payment method field mappings, state machine mapping
• Pyz\Zed\CheckoutRestApi\CheckoutRestApiConfig — Zed-side checkout configuration
• Pyz\Zed\CheckoutRestApi\CheckoutRestApiDependencyProvider — Zed-side checkout plugins
• Pyz\Shared\CheckoutRestApi\Transfer\checkout_rest_api.transfer.xml — custom transfer definitions

Create:

• src/Pyz/Checkout/src/Pyz/Glue/Checkout/CheckoutDependencyProvider.php — request expanders and validators
• src/Pyz/Checkout/src/Pyz/Glue/Checkout/CheckoutConfig.php — payment method to state machine mapping

See Migrate CheckoutRestApi for the full file content.

OrdersRestApi to Sales

Delete: src/Pyz/OrdersRestApi/ (entire directory)

This module contained:

• Pyz\Glue\OrdersRestApi\OrdersRestApiDependencyProvider — order item attribute mappers and order details attribute mappers

Create: src/Pyz/Sales/src/Pyz/Glue/Sales/SalesDependencyProvider.php

The new module registers order item expander and order details expander plugins. The plugin interface naming changed from RestOrderItemsAttributesMapperPlugin to OrderItemExpanderPlugin. See Migrate OrdersRestApi for the full file content.

MerchantsRestApi — delete only

Delete: src/Pyz/MerchantsRestApi/ (entire directory)

This module contained:

• Pyz\Glue\MerchantsRestApi\MerchantsRestApiDependencyProvider — merchant category attribute mapper plugin

No replacement needed. Merchant attribute mapping is now handled internally by the API Platform Merchant module provider.

SharedCartsRestApi to Authentication

Delete: src/Pyz/SharedCartsRestApi/ (entire directory)

This module contained:

• Pyz\Glue\SharedCartsRestApi\SharedCartsRestApiDependencyProvider — company user storage provider plugin

Create: src/Pyz/Authentication/src/Pyz/Glue/Authentication/AuthenticationDependencyProvider.php

Company user identity resolution has moved to the centralized Authentication module. The new module registers customer identity expander plugins via AuthenticationExtension. See Migrate SharedCartsRestApi for the full file content.

CustomerAccessRestApi — delete only

Delete: src/Pyz/CustomerAccessRestApi/ (entire directory)

This module contained:

• Pyz\Glue\CustomerAccessRestApi\CustomerAccessRestApiConfig — content type to REST resource type mapping

No replacement needed. Customer access control is now handled through API Platform security expressions in YAML resource definitions. See Migrate CustomerAccessRestApi.

5. Migrate custom plugin implementations

If your project implemented custom plugins against old *RestApiExtension interfaces, you need to update them to the new extension interfaces.

Cart extension plugins

Checkout extension plugins

Customer extension plugins

Authentication extension plugins (new)

These are new plugin interfaces introduced by the API Platform architecture:

6. Migrate custom REST API endpoints

If your project created custom Glue REST API endpoints in src/Pyz/, you need to migrate them to the API Platform architecture.

Old pattern

In the legacy Glue REST API, a custom endpoint required:

1. A ResourceRoutePlugin registered in GlueApplicationDependencyProvider::getResourceRoutePlugins()
2. A RestResourceController with action methods (getAction, postAction, etc.)
3. REST attributes transfer objects defined in transfer.xml
4. A mapper class to convert between domain transfers and REST attributes
5. Optional: relationship plugins, request validators

New pattern

In API Platform, a custom endpoint requires:

1. A YAML resource definition in resources/api/storefront/your-resource.resource.yml
2. A YAML validation definition in resources/api/storefront/your-resource.validation.yml
3. A Provider class extending AbstractStorefrontProvider (for GET operations)
4. A Processor class extending AbstractStorefrontProcessor (for POST/PATCH/DELETE operations)
5. Auto-generated resource class (generated by api:generate from the YAML definition)

Migration steps for a custom endpoint

1. Create the YAML resource definition at src/Pyz/{YourModule}/resources/api/storefront/your-resource.resource.yml:

resource:
    name: YourResources
    shortName: your-resources
    description: 'Description of your resource'

    provider: Pyz\Glue\YourModule\Api\Storefront\Provider\YourResourcesStorefrontProvider
    processor: Pyz\Glue\YourModule\Api\Storefront\Processor\YourResourcesStorefrontProcessor

    paginationEnabled: true
    security: "is_granted('ROLE_CUSTOMER')"

    operations:
        - type: GetCollection
        - type: Get
        - type: Post
        - type: Patch
        - type: Delete

    properties:
        id:
            type: string
            identifier: true
            writable: false
            readable: true
        name:
            type: string
            readable: true
            writable: true

2. Create the validation definition at src/Pyz/{YourModule}/resources/api/storefront/your-resource.validation.yml:

post:
    name:
        - NotBlank: ~

3. Create the Provider class:

<?php

declare(strict_types = 1);

namespace Pyz\Glue\YourModule\Api\Storefront\Provider;

use Spryker\Glue\GlueStorefrontApiApplication\Api\Provider\AbstractStorefrontProvider;

class YourResourcesStorefrontProvider extends AbstractStorefrontProvider
{
    protected function provideCollection(): array
    {
        // Load and return collection of resource objects
        return [];
    }

    protected function provideItem(): ?object
    {
        // Load and return single resource object
        return null;
    }
}

4. Create the Processor class:

<?php

declare(strict_types = 1);

namespace Pyz\Glue\YourModule\Api\Storefront\Processor;

use Spryker\Glue\GlueStorefrontApiApplication\Api\Processor\AbstractStorefrontProcessor;

class YourResourcesStorefrontProcessor extends AbstractStorefrontProcessor
{
    protected function processPost(mixed $data): mixed
    {
        // Handle POST — $data is the auto-generated resource object
        return $data;
    }

    protected function processPatch(mixed $data): mixed
    {
        // Handle PATCH
        return $data;
    }

    protected function processDelete(): mixed
    {
        // Handle DELETE
        return null;
    }
}

5. Generate the resource class and clear the cache:

docker/sdk cli glue api:generate
docker/sdk cli glue cache:clear

6. Remove the old ResourceRoutePlugin from GlueApplicationDependencyProvider::getResourceRoutePlugins().

7. Delete the old controller, mapper, and REST attributes transfer classes.

7. Architecture changes reference

This table summarizes the paradigm shifts for quick reference when migrating project-level code.

After migration

After completing the cross-cutting cleanup, regenerate transfers, API resources, and clear the cache:

docker/sdk cli console transfer:generate
docker/sdk cli glue api:generate
docker/sdk cli glue cache:clear

Clean up unused imports and verify that your GlueApplicationDependencyProvider compiles without errors. Any remaining use statements pointing to deleted RestApi modules will cause autoload failures.