Spryker documentation center. https://docs.spryker.com/ Wed, 20 May 2026 08:20:33 +0000 Jekyll v4.2.2 <p>The Back Office Configuration Framework is a structured approach to exposing business-relevant configuration options directly in the Spryker Back Office. Instead of defining configuration in code or YAML files that require redeployment, businesses can manage defined behaviors through structured UI pages. Developers define configuration options once in YAML, and the framework automatically renders them as configurable Back Office interfaces.</p> <hr /> <h2 id="business-problems-it-solves">Business problems it solves</h2> <p>Managing configuration in traditional commerce platforms creates friction between technical and business teams:</p> <ul> <li>Configuration changes require developer involvement, code modifications, and a full deployment cycle.</li> <li>Business teams depend on IT to adjust behaviors that are fundamentally business decisions.</li> <li>YAML and code-level configuration is inaccessible to non-technical stakeholders and prone to error.</li> <li>Each configuration change introduces risk, slows down operations, and increases the total cost of change.</li> </ul> <p>The Back Office Configuration Framework addresses these challenges by creating a clear, controlled boundary between what developers define and what business users can adjust.</p> <hr /> <h2 id="key-value-for-your-business">Key value for your business</h2> <ul> <li> <p><strong>Faster time to change</strong> Business users adjust configured behaviors directly in the Back Office. No code change, no pull request, no deployment required.</p> </li> <li> <p><strong>Reduced operational risk</strong> Configuration is exposed through structured, validated UI pages. Business users work within defined options rather than editing raw configuration files.</p> </li> <li> <p><strong>Developer efficiency</strong> Developers define configuration options once in YAML. The framework handles rendering, validation, and persistence automatically, eliminating repetitive UI work.</p> </li> <li> <p><strong>Consistent experience</strong> All configuration pages follow the same structure and interaction patterns, making it easier for business users to navigate and manage settings across features.</p> </li> <li> <p><strong>Extensibility by design</strong> The framework supports both out of the box Spryker features and project-specific customizations, so teams can introduce new configurable behaviors without building new infrastructure.</p> </li> </ul> <hr /> <h2 id="who-benefits-and-how">Who benefits and how</h2> <h3 id="for-business-leaders">For business leaders</h3> <ul> <li> <p><strong>Lower cost of change</strong> Adjusting business behaviors no longer requires a development sprint or deployment window. Teams can respond to market conditions and business needs faster.</p> </li> <li> <p><strong>Reduced dependency on IT</strong> Business teams gain direct control over selected configuration options without needing to involve developers for every adjustment.</p> </li> <li> <p><strong>Stable, governed configurability</strong> The framework exposes only explicitly defined options. Business users operate within guardrails set by the development team, reducing the risk of misconfiguration.</p> </li> </ul> <h3 id="for-product-and-commerce-teams">For product and commerce teams</h3> <ul> <li> <p><strong>Self-service configuration</strong> Manage feature behavior directly from the Back Office, using familiar UI patterns. No need to understand YAML syntax or request a deployment.</p> </li> <li> <p><strong>Faster iteration</strong> Test different configurations, observe results, and adjust without waiting for a release cycle.</p> </li> <li> <p><strong>Visibility into configurable options</strong> All available configuration options are surfaced in one place, making it easy to understand what can be changed and what the current settings are.</p> </li> </ul> <h3 id="for-developers-and-architects">For developers and architects</h3> <ul> <li> <p><strong>Define once, render automatically</strong> Declare configuration options in YAML. The framework generates the corresponding Back Office UI, saving significant development and maintenance effort.</p> </li> <li> <p><strong>Separation of concerns</strong> Configuration definition stays with the developer; configuration management becomes a business user activity. This boundary is enforced by the framework.</p> </li> <li> <p><strong>Standardized patterns</strong> Avoid building custom configuration UIs for each feature. The framework provides consistent infrastructure that all teams benefit from.</p> </li> </ul> <hr /> <h2 id="key-capabilities">Key capabilities</h2> <h3 id="support-for-out-of-the-box-and-custom-features">Support for out of the box and custom features</h3> <p>The framework supports configuration for existing Spryker out of the box features as well as project-specific customizations. Teams can use it to expose configuration options for both standard platform capabilities and bespoke features built for a specific project.</p> <h3 id="structured-and-controlled-business-configurability">Structured and controlled business configurability</h3> <p>Selected business-relevant configuration moves from code level to UI level without exposing low-level technical complexity. The developer controls which options are available, what values are valid, and how they are presented. The business user controls what value is set, within those defined parameters.</p> <h3 id="out-of-the-box-implementations">Out of the box implementations</h3> <p>The Back Office Configuration Framework ships with the following out of the box implementations.</p> <p><strong>B2B Product Availability Display</strong></p> <p>The initial release ships with a configuration UI for B2B Product Availability Display. This implementation demonstrates the framework in a real-world use case, allowing business users to configure how product availability information is presented to B2B buyers directly from the Back Office.</p> <p><strong>Basic Shop Theme</strong></p> <p>The second out of the box implementation provides a configuration UI for shop branding. Business Admins can set theme colors, logo URLs, and custom CSS for the Storefront, Back Office, and Merchant Portal without code changes or redeployment. For details, see <a href="/docs/pbc/all/back-office/latest/base-shop/basic-shop-theme-feature-overview.html">Basic Shop Theme feature overview</a>.</p> <hr /> <h2 id="how-it-works">How it works</h2> <p>The Back Office Configuration Framework follows a developer-first definition approach with a business-user-facing runtime experience:</p> <ol> <li> <p><strong>Developer defines configuration options in YAML</strong> The developer declares the available configuration options, their data types, validation rules, and default values in a structured YAML definition.</p> </li> <li> <p><strong>Framework generates the Back Office UI</strong> The framework reads the YAML definition and automatically renders the corresponding configuration page in the Back Office, including form fields, labels, and validation feedback.</p> </li> <li> <p><strong>Business user manages configuration</strong> A Back Office user with appropriate permissions accesses the configuration page, adjusts the available options, and saves changes.</p> </li> <li> <p><strong>Changes take effect without redeployment</strong> Configuration updates are stored and applied at runtime. No code changes or deployments are required.</p> </li> </ol> <hr /> <h2 id="comparison-to-traditional-configuration-approaches">Comparison to traditional configuration approaches</h2> <h3 id="code-level-configuration">Code-level configuration</h3> <p><strong>Traditional approach:</strong> Configuration values are hardcoded or set in PHP configuration files. Changing a value requires a code change, review, and deployment.</p> <p><strong>Back Office Configuration Framework:</strong> Configuration values are managed in the Back Office UI. Changes take effect immediately, within the boundaries defined by the developer.</p> <h3 id="yaml-based-configuration">YAML-based configuration</h3> <p><strong>Traditional approach:</strong> Configuration is declared in YAML files that are part of the codebase. Changing a value requires editing a file, committing the change, and triggering a deployment.</p> <p><strong>Back Office Configuration Framework:</strong> YAML is still used, but only by developers to define what options are available. Business users interact with the resulting UI, not with YAML directly.</p> <h3 id="custom-configuration-uis">Custom configuration UIs</h3> <p><strong>Traditional approach:</strong> Each feature that requires business-user configuration needs a custom-built UI, resulting in inconsistent experiences and duplicated development effort.</p> <p><strong>Back Office Configuration Framework:</strong> All configurable features share the same framework-generated UI infrastructure, reducing development effort and ensuring a consistent experience.</p> <hr /> <h2 id="related-features">Related features</h2> <table> <thead> <tr> <th>Feature</th> <th>Link</th> </tr> </thead> <tbody> <tr> <td>Configuration Management Development Guide</td> <td><a href="/docs/dg/dev/backend-development/configuration-management.html">Developer guide</a></td> </tr> </tbody> </table> Wed, 20 May 2026 08:16:55 +0000 https://docs.spryker.com/docs/pbc/all/back-office/latest/base-shop/backoffice-configuration-framework.html https://docs.spryker.com/docs/pbc/all/back-office/latest/base-shop/backoffice-configuration-framework.html This document provides solutions to common issues when working with API Platform in Spryker. ## Generation issues ### Resources not generating **Symptom:** Running `docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate` completes but no resources are created. **Possible causes:** 1. **Schema file location is incorrect** ```bash ❌ src/Pyz/Glue/Customer/api/customers.resource.yml ✅ src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml ``` 2. **API type not configured** Check `config/{APPLICATION}/packages/spryker_api_platform.php`: ```php $containerConfigurator->extension('spryker_api_platform', [ 'api_types' => [ 'backend', // Must match directory name ], ]); ``` 3. **Bundle not registered** Verify `config/{APPLICATION}/bundles.php` includes: ```php SprykerApiPlatformBundle::class => ['all' => true], ``` **Solution:** ```bash # Debug to see what's being discovered docker/sdk cli glue api:debug --list # Check schema validation docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only # Force regeneration docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --force ``` ### Schema validation errors **Symptom:** Generation fails with schema validation errors. **Common errors:** ```bash # Error: Invalid operation type ❌ operations: - type: CREATE ✅ operations: - type: Post # Error: Invalid property type ❌ type: int ✅ type: integer # Error: Missing resource name ❌ resource: shortName: customers ✅ resource: name: Customers shortName: customers ``` **Solution:** 1. Check schema against examples in documentation 2. Use `--validate-only` flag for detailed validation: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only ``` 3. Inspect merged schema: ```bash docker/sdk cli glue api:debug resource-name --show-merged ``` ## Runtime issues ### Provider/Processor not found **Symptom:** ```bash Error: Class "Pyz\Glue\Customer\Api\Backend\Provider\CustomerBackendProvider" not found ``` **Possible causes:** 1. Class doesn't exist or namespace is wrong 2. Not registered in the Dependency Injection container 3. Typo in the schema file **Solution:** 1. Verify the class exists and namespace matches: ```php namespace Pyz\Glue\Customer\Api\Backend\Provider; class CustomerBackendProvider implements ProviderInterface ``` 2. Ensure services are auto-discovered in `ApplicationServices.php`: ```php $services->load('Pyz\\Glue\\', '../../../src/Pyz/Glue/'); ``` 3. Check class name in the resource schema file of the module matches exactly: ```yaml provider: "Pyz\\Glue\\Customer\\Api\\Backend\\Provider\\CustomerBackendProvider" ``` ### Validation not working **Symptom:** API accepts invalid data despite validation rules. **Possible causes:** 1. Validation schema file not found 2. Wrong operation name in validation schema 3. Validation groups not matching **Solution:** 1. Ensure validation file exists: ```bash ✅ resources/api/backend/customers.validation.yml ``` 2. Match operation names to HTTP methods: ```yaml post: # For POST /customers email: - NotBlank patch: # For PATCH /customers/{id} email: - Optional: constraints: - Email ``` 3. Check generated resource class (for example `Generated\Api\Storefront\CustomersStorefrontResource`) has validation attributes: ```php #[Assert\NotBlank(groups: ['customers:create'])] #[Assert\Email(groups: ['customers:create'])] public ?string $email = null; ``` ### API documentation UI not displaying correctly **Symptom:** When accessing the root URL of your API application, you see: - Missing styles/CSS - Broken JavaScript functionality - Plain HTML without formatting - "Failed to load resource" errors in browser docker/sdk cli glue **Cause:** Assets were not installed after API Platform integration. **Solution:** Run the appropriate assets:install command for your application: ### For Glue application ```bash docker/sdk cli glue assets:install public/Glue/assets --symlink ``` ### For GlueStorefront ```bash docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue assets:install public/GlueStorefront/assets/ --symlink ``` ### For GlueBackend ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue assets:install public/GlueBackend/assets/ --symlink ``` Then verify the documentation UI loads correctly by visiting the root URL: - Storefront: `https://glue-storefront.mysprykershop.com/` - Backend: `https://glue-backend.mysprykershop.com/` {% info_block warningBox "Required after integration" %} The `assets:install` command must be run after integrating API Platform and whenever API Platform assets are updated. This is a required step documented in [How to integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html). {% endinfo_block %} ### 404 Not Found for API endpoints **Symptom:** API requests return 404. **Possible causes:** 1. Router not configured 2. Routes not loaded 3. Wrong URL format **Solution:** 1. Verify `SymfonyFrameworkRouterPlugin` is registered: ```php // RouterDependencyProvider protected function getRouterPlugins(): array { return [ new GlueRouterPlugin(), new SymfonyFrameworkRouterPlugin(), // Must be present ]; } ``` 2. Check API documentation for correct URLs: ```bash Storefront: https://glue-storefront.mysprykershop.com/ Backend: https://glue-backend.mysprykershop.com/ ``` The interactive API documentation is available at the root URL of each application. 3. Use correct URL format: ```bash ❌ /api/v1/customers ✅ /customers ``` ### Pagination not working **Symptom:** All results returned instead of paginated response. **Solution:** 1. Enable pagination in the schema file of the defining module: ```yaml resource: paginationEnabled: true paginationItemsPerPage: 10 ``` 2. Return `PaginatorInterface` from provider: ```php use ApiPlatform\State\Pagination\TraversablePaginator; return new TraversablePaginator( new \ArrayObject($results), $currentPage, $itemsPerPage, $totalItems ); ``` 3. Use pagination query parameters: ```bash GET /customers?page=2&itemsPerPage=20 ``` ### Client cannot change items per page **Symptom:** The `itemsPerPage` query parameter is ignored. **Solution:** Enable client-side items-per-page control and set a maximum limit in the resource schema: ```yaml resource: paginationEnabled: true paginationItemsPerPage: 10 paginationClientItemsPerPage: true paginationMaximumItemsPerPage: 100 ``` Without `paginationClientItemsPerPage: true`, the `itemsPerPage` query parameter has no effect. The `paginationMaximumItemsPerPage` option prevents clients from requesting excessively large pages. ### Client cannot disable pagination **Symptom:** The `pagination=false` query parameter is ignored and results are still paginated. **Solution:** Enable client-side pagination control in the resource schema: ```yaml resource: paginationClientEnabled: true ``` Without `paginationClientEnabled: true`, the `pagination` query parameter has no effect. For a full reference of all pagination options, see [Resource Schemas — Pagination](/docs/dg/dev/architecture/api-platform/resource-schemas.html#pagination). ## Dependency Injection issues ### Services not autowired **Symptom:** ```bash Cannot autowire service "CustomerBackendProvider": argument "$customerFacade" references class "CustomerFacadeInterface" but no such service exists. ``` **Solution:** 1. Register facade in the respective applications `ApplicationServices.php`: ```php use Pyz\Zed\Customer\Business\CustomerFacadeInterface; use Pyz\Zed\Customer\Business\CustomerFacade; $services->set(CustomerFacadeInterface::class, CustomerFacade::class); ``` 2. Ensure constructor uses interface type hints: ```php public function __construct( private CustomerFacadeInterface $customerFacade, // ✅ Interface ) {} ``` ## Performance issues ### Slow API responses **Symptom:** API endpoints respond slowly. **Solution:** 1. Enable Symfony cache: ```bash docker/sdk cli glue cache:warmup ``` 2. Use pagination for collections 3. Optimize database queries in Provider 4. Use API Platform's built-in caching features ## Development tips ### Debugging schema merging See which schemas contribute to final resource: ```bash docker/sdk cli glue api:debug customers --api-type=backend --show-sources ``` Output: ```bash Source Files (priority order): ✓ vendor/spryker/customer/resources/api/backend/customers.resource.yml (CORE) ✓ src/SprykerFeature/CRM/resources/api/backend/customers.resource.yml (FEATURE) ✓ src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml (PROJECT) ``` ### Inspecting generated code View the generated resource class: ```bash cat src/Generated/Api/Backend/CustomersBackendResource.php ``` Check for: - Correct property types - Validation attributes - API Platform metadata ### Testing with dry-run Preview generation without writing files: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --dry-run ``` ## Getting help If you encounter issues not covered here: 1. **Check logs:** ```bash tail -f var/log/application.log tail -f var/log/exception.log ``` 2. **Enable debug mode:** ```php // config/{APPLICATION}/packages/spryker_api_platform.php $containerConfigurator->extension('spryker_api_platform', [ 'debug' => true, ]); ``` 3. **Validate environment:** ```bash php -v # Check PHP version (8.1+) composer show | grep api-platform docker/sdk cli glue debug:container | grep -i api ``` 4. **Common error patterns:** | Error | Likely cause | Solution | |-------|--------------|----------| | `Class not found` | Autoloading issue | Run `composer dump-autoload` | | `Service not found` | DI configuration | Check `ApplicationServices.php` | | `Route not found` | Router not configured | Add `SymfonyFrameworkRouterPlugin` | | `Validation failed` | Schema mismatch | Regenerate with `--force` | | `Cache is stale` | Outdated cache | Run `cache:clear` | | API docs UI broken/unstyled | Assets not installed | Run `docker/sdk cli glue /glue assets:install` | ## Next steps - [API Platform](/docs/dg/dev/architecture/api-platform.html) - Overview and concepts - [How to integrate API Platform](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html) - Setup guide - [API Platform Enablement](/docs/dg/dev/architecture/api-platform/enablement.html) - Creating resources - [Resource Schemas](/docs/dg/dev/architecture/api-platform/resource-schemas.html) - Resource schema reference - [Validation Schemas](/docs/dg/dev/architecture/api-platform/validation-schemas.html) - Validation schema reference - [API Platform Testing](/docs/dg/dev/architecture/api-platform/testing.html) - Testing guide Tue, 19 May 2026 12:29:11 +0000 https://docs.spryker.com/docs/dg/dev/architecture/api-platform/troubleshooting.html https://docs.spryker.com/docs/dg/dev/architecture/api-platform/troubleshooting.html This document describes how to write and run tests for your API Platform resources in your project. ## Overview API Platform provides a comprehensive testing infrastructure built on top of: - **Codeception**: Test framework for PHP - **API Platform Test Client**: Specialized HTTP client for API testing - **PHPUnit Assertions**: Rich set of assertion methods - **Test Helpers**: Custom helpers for test data management The testing infrastructure supports both Backend and Storefront API types with dedicated base classes and configuration. ## Test architecture ### Test class hierarchy ```bash AbstractApiTestCase (base class from core) ├── BackendApiTestCase (for Backend API tests) └── StorefrontApiTestCase (for Storefront API tests) ``` ### Key components | Component | Purpose | |-----------|---------| | `AbstractApiTestCase` | Base class providing API Platform integration | | `BackendApiTestCase` | Pre-configured for Backend API testing | | `StorefrontApiTestCase` | Pre-configured for Storefront API testing | | `ApiTestKernel` | Lightweight Symfony kernel for testing | | `ApiTestAssertionsTrait` | API-specific assertions (from API Platform) | ### Test helper classes The testing infrastructure provides specialized Codeception helpers to streamline test development: | Helper Class | Purpose | |--------------|---------| | `BootstrapHelper` | Configures application plugin providers for test environments via codeception.yml. Allows different test suites to use different factory implementations without hardcoding dependencies in test infrastructure. | | `ApiPlatformHelper` | Configures resource generation and cache lifecycle for the test kernel. Has two modes — `project` (default, preserves the compiled container for speed) and `core` (generates fresh resources per suite and cleans the container cache afterwards, used when testing the API Platform module itself). See [ApiPlatformHelper modes](#apiplatformhelper-modes). | | `ApiPlatformConfigBuilder` | Provides a fluent interface for building test-specific API Platform configurations. Useful for creating isolated test scenarios with custom settings. | | `ApiResourceGeneratorHelper` | Assists with testing resource generation functionality. Provides methods to generate test resources, validate generation output, and clean up generated files. | These helpers are automatically available in your test cases through the Codeception actor and provide essential functionality for testing API Platform resources effectively. ## Setting up your test environment ### 1. Configure autoloading for generated test resources Update your project-level `composer.json` to include the test API namespace: `composer.json` (project root) ```json { "autoload-dev": { "psr-4": { "PyzTest\\": "tests/PyzTest/", "Generated\\TestApi\\": "tests/_data/Api/" } } } ``` ### 2. Optional: Configure application plugin providers If your tests require application plugins to be registered (for example, service providers or middleware), configure the `BootstrapHelper` in your suite's `codeception.yml`: `tests/PyzTest/Glue/Customer/BackendApi/codeception.yml` ```yaml modules: enabled: - \SprykerTest\Shared\Testify\Helper\BootstrapHelper: applicationPluginProvider: class: Spryker\Glue\GlueBackendApiApplication\GlueBackendApiApplicationFactory method: getApplicationPlugins ``` For Storefront API tests, use the appropriate factory: `tests/PyzTest/Glue/Customer/StorefrontApi/codeception.yml` ```yaml modules: enabled: - \SprykerTest\Shared\Testify\Helper\BootstrapHelper: applicationPluginProvider: class: Spryker\Glue\GlueStorefrontApiApplication\GlueStorefrontApiApplicationFactory method: getApplicationPlugins ``` **Configuration options:** - `class`: The fully qualified class name of the factory that provides application plugins - `method`: The method name to call on the factory (typically `getApplicationPlugins`) If no `applicationPluginProvider` is configured, the helper returns an empty array, and tests run without additional application plugins. ### 3. Create test directory structure ```bash tests/ ├── PyzTest/ │ └── Glue/ │ └── Customer/ │ ├── BackendApi/ │ │ ├── codeception.yml │ │ └── CustomersBackendApiTest.php │ └── StorefrontApi/ │ ├── codeception.yml │ └── CustomersStorefrontApiTest.php └── _data/ └── Api/ ├── Backend/ │ └── CustomersBackendResource.php (generated) └── Storefront/ └── CustomersStorefrontResource.php (generated) ``` ### 4. Generate API resources for testing The resources and the container are automatically generated right before the test suite runs. #### Automatic resource generation and cleanup The test infrastructure handles resource lifecycle automatically: - **Generation** (core mode only): Test-specific API resources are generated into `tests/_data/Api/{ApiType}/` before each suite executes. In project mode, the helper instead validates that the project-generated resources already exist on disk. - **Cleanup** (core mode only): The `ApiPlatformHelper` clears the compiled Symfony test kernel cache and the generated resources after the suite completes. Project mode deliberately skips this step so the compiled container can be reused across runs. - **Mode selection**: Choose the mode in `codeception.yml` — see [ApiPlatformHelper modes](#apiplatformhelper-modes) below for the trade-offs. This automation ensures that: - Tests always run against the latest schema definitions - No manual cache clearing is required between test runs - Test failures related to stale cache are eliminated ## Writing Backend API tests ### Basic test structure Backend API tests extend `BackendApiTestCase` and use the `BackendApiTester` tester which gets automatically injected into your tests by Codeception. `tests/PyzTest/Glue/Customer/BackendApi/CustomersBackendApiTest.php` ```php <?php namespace PyzTest\Glue\Customer\BackendApi; use PyzTest\Glue\Customer\BackendApiTester; use SprykerTest\Shared\ApiPlatform\Test\BackendApiTestCase; /** * @group PyzTest * @group Glue * @group Customer * @group BackendApi * @group CustomersBackendApiTest */ class CustomersBackendApiTest extends BackendApiTestCase { protected BackendApiTester $tester; public function testGivenValidDataWhenCreatingCustomerViaPostThenCustomerIsCreatedSuccessfully(): void { // Arrange $customerData = [ 'email' => 'john.doe@example.com', 'firstName' => 'John', 'lastName' => 'Doe', ]; // Act static::createClient()->request('POST', '/customers', ['json' => $customerData]); // Assert $this->assertResponseIsSuccessful(); $this->assertResponseStatusCodeSame(201); $this->assertJsonContains(['email' => 'john.doe@example.com']); $this->assertJsonContains(['firstName' => 'John']); $this->assertJsonContains(['lastName' => 'Doe']); } } ``` ### Testing GET operations #### Single resource ```php public function testGivenExistingCustomerWhenRetrievingViaGetThenCustomerDataIsReturned(): void { // Arrange $customerTransfer = $this->tester->haveCustomer([ 'email' => 'existing@example.com', 'firstName' => 'Jane', 'lastName' => 'Smith', ]); // Act static::createClient()->request( 'GET', sprintf('/customers/%s', $customerTransfer->getCustomerReference()) ); // Assert $this->assertResponseIsSuccessful(); $this->assertJsonContains(['email' => 'existing@example.com']); $this->assertJsonContains(['firstName' => 'Jane']); } ``` #### Collection with pagination ```php public function testGivenMultipleCustomersWhenRetrievingCollectionViaGetThenAllCustomersAreReturned(): void { // Arrange $this->tester->haveCustomer(['email' => 'customer1@example.com']); $this->tester->haveCustomer(['email' => 'customer2@example.com']); $this->tester->haveCustomer(['email' => 'customer3@example.com']); // Act static::createClient()->request('GET', '/customers'); // Assert $this->assertResponseIsSuccessful(); $this->assertJsonContains(['@type' => 'Collection']); $this->assertJsonContains(['totalItems' => 3]); } public function testGivenPaginationParamsWhenRetrievingCollectionThenPaginatedResultsAreReturned(): void { // Arrange for ($i = 1; $i <= 15; $i++) { $this->tester->haveCustomer(['email' => sprintf('customer%d@example.com', $i)]); } // Act static::createClient()->request('GET', '/customers?page=2&itemsPerPage=5'); // Assert $this->assertResponseIsSuccessful(); $this->assertJsonContains(['@type' => 'Collection']); $this->assertJsonContains(['view' => ['@id' => '/customers?page=2&itemsPerPage=5']]); } ``` ### Testing POST operations #### Successful creation ```php public function testGivenValidDataWhenCreatingCustomerViaPostThenCustomerIsCreatedSuccessfully(): void { // Arrange $customerData = [ 'email' => 'new.customer@example.com', 'firstName' => 'New', 'lastName' => 'Customer', ]; // Act $response = static::createClient()->request('POST', '/customers', [ 'json' => $customerData, ]); // Assert $this->assertResponseIsSuccessful(); $this->assertResponseStatusCodeSame(201); $this->assertJsonContains($customerData); $this->assertResponseHeaderSame('Content-Type', 'application/ld+json; charset=utf-8'); // Verify the resource was created and has an ID $responseData = $response->toArray(); $this->assertArrayHasKey('customerReference', $responseData); $this->assertNotEmpty($responseData['customerReference']); } ``` #### Validation errors ```php public function testGivenInvalidDataWhenCreatingCustomerViaPostThenValidationErrorIsReturned(): void { // Arrange $invalidCustomerData = [ 'email' => 'invalid-email', // Invalid email format 'firstName' => '', // Empty first name ]; // Act static::createClient()->request('POST', '/customers', [ 'json' => $invalidCustomerData, ]); // Assert $this->assertResponseStatusCodeSame(422); $this->assertResponseHeaderSame('Content-Type', 'application/ld+json; charset=utf-8'); $this->assertJsonContains(['@type' => 'ConstraintViolationList']); $this->assertJsonContains([ 'violations' => [ ['propertyPath' => 'email'], ['propertyPath' => 'firstName'], ['propertyPath' => 'lastName'], ], ]); } ``` #### Business rule violations ```php public function testGivenDuplicateEmailWhenCreatingCustomerViaPostThenErrorIsReturned(): void { // Arrange $this->tester->haveCustomer(['email' => 'duplicate@example.com']); $duplicateData = [ 'email' => 'duplicate@example.com', 'firstName' => 'Duplicate', 'lastName' => 'Customer', ]; // Act static::createClient()->request('POST', '/customers', [ 'json' => $duplicateData, ]); // Assert $this->assertResponseStatusCodeSame(422); $this->assertJsonContains(['@type' => 'Error']); $this->assertJsonContains(['detail' => 'Customer with this email already exists']); } ``` ### Testing PATCH operations ```php public function testGivenExistingCustomerWhenUpdatingViaPatchThenCustomerIsUpdatedSuccessfully(): void { // Arrange $customerTransfer = $this->tester->haveCustomer([ 'email' => 'update@example.com', 'firstName' => 'Original', 'lastName' => 'Name', ]); $updateData = [ 'firstName' => 'Updated', 'lastName' => 'Name', ]; // Act static::createClient()->request( 'PATCH', sprintf('/customers/%s', $customerTransfer->getCustomerReference()), [ 'json' => $updateData, 'headers' => [ 'Content-Type' => 'application/merge-patch+json', ], ] ); // Assert $this->assertResponseIsSuccessful(); $this->assertJsonContains(['firstName' => 'Updated']); $this->assertJsonContains(['email' => 'update@example.com']); // Unchanged } ``` ### Testing DELETE operations ```php public function testGivenExistingCustomerWhenDeletingViaDeleteThenCustomerIsDeletedSuccessfully(): void { // Arrange $customerTransfer = $this->tester->haveCustomer([ 'email' => 'delete@example.com', ]); // Act static::createClient()->request( 'DELETE', sprintf('/customers/%s', $customerTransfer->getCustomerReference()) ); // Assert $this->assertResponseStatusCodeSame(204); $this->assertResponseHasNoContent(); } public function testGivenNonExistentCustomerWhenDeletingViaDeleteThen404IsReturned(): void { // Act static::createClient()->request('DELETE', '/customers/NON-EXISTENT-REFERENCE'); // Assert $this->assertResponseStatusCodeSame(404); } ``` ### Testing relationships The relationships feature enables resources to include related resources via the `?include=` query parameter. For details on configuring relationships, see [Relationships](/docs/dg/dev/architecture/api-platform/relationships.html). #### Testing include parameter ```php public function testGivenCustomerWithAddressesWhenRequestingWithIncludeThenAddressesAreIncluded(): void { // Arrange $customerTransfer = $this->tester->haveCustomer(); $this->tester->haveAddress(['customerReference' => $customerTransfer->getCustomerReference()]); $this->tester->haveAddress(['customerReference' => $customerTransfer->getCustomerReference()]); // Act $response = static::createClient()->request( 'GET', sprintf('/customers/%s?include=addresses', $customerTransfer->getCustomerReference()) ); // Assert $this->assertResponseIsSuccessful(); $data = $response->toArray(); // Assert relationships section exists $this->assertArrayHasKey('relationships', $data['data']); $this->assertArrayHasKey('addresses', $data['data']['relationships']); // Assert included section contains addresses $this->assertArrayHasKey('included', $data); $this->assertCount(2, $data['included']); } ``` #### Testing JSON:API structure ```php public function testGivenIncludedResourcesWhenRetrievingThenJsonApiStructureIsValid(): void { // Arrange $customerTransfer = $this->tester->haveCustomer(); $this->tester->haveAddress(['customerReference' => $customerTransfer->getCustomerReference()]); // Act $response = static::createClient()->request( 'GET', sprintf('/customers/%s?include=addresses', $customerTransfer->getCustomerReference()) ); // Assert $data = $response->toArray(); // Verify main resource structure $this->assertArrayHasKey('data', $data); $this->assertArrayHasKey('type', $data['data']); $this->assertArrayHasKey('id', $data['data']); $this->assertArrayHasKey('attributes', $data['data']); $this->assertArrayHasKey('relationships', $data['data']); // Verify included resources structure foreach ($data['included'] as $includedResource) { $this->assertArrayHasKey('type', $includedResource); $this->assertArrayHasKey('id', $includedResource); $this->assertArrayHasKey('attributes', $includedResource); } // Verify relationship linkage $relationshipData = $data['data']['relationships']['addresses']['data']; foreach ($relationshipData as $linkage) { $this->assertArrayHasKey('type', $linkage); $this->assertArrayHasKey('id', $linkage); } } ``` ## Writing Storefront API tests ### Basic test structure Storefront API tests extend `StorefrontApiTestCase` and typically use mocks for read-only operations. `tests/PyzTest/Glue/Customer/StorefrontApi/CustomersStorefrontApiTest.php` ```php <?php namespace PyzTest\Glue\Customer\StorefrontApi; use Codeception\Stub; use Pyz\Client\Customer\CustomerClientInterface; use PyzTest\Glue\Customer\StorefrontApiTester; use SprykerTest\Shared\ApiPlatform\Test\StorefrontApiTestCase; /** * @group PyzTest * @group Glue * @group Customer * @group StorefrontApi * @group CustomersStorefrontApiTest */ class CustomersStorefrontApiTest extends StorefrontApiTestCase { protected StorefrontApiTester $tester; public function testGivenAuthenticatedCustomerWhenRetrievingProfileViaGetThenCustomerDataIsReturned(): void { // Arrange $customerClientStub = Stub::makeEmpty(CustomerClientInterface::class, [ 'getCustomer' => (new CustomerTransfer()) ->setEmail('customer@example.com') ->setFirstName('John') ->setLastName('Doe'), ]); static::getContainer()->set(CustomerClientInterface::class, $customerClientStub); // Act static::createClient()->request('GET', '/customers/me'); // Assert $this->assertResponseIsSuccessful(); $this->assertJsonContains(['email' => 'customer@example.com']); } } ``` ### Testing with service mocks ```php public function testGivenMultipleCustomersWhenRetrievingCollectionViaGetThenAllCustomersAreReturned(): void { // Arrange $customerClientStub = Stub::makeEmpty(CustomerClientInterface::class, [ 'getCustomerCollection' => [ (new CustomerTransfer())->setEmail('customer1@example.com'), (new CustomerTransfer())->setEmail('customer2@example.com'), ], ]); static::getContainer()->set(CustomerClientInterface::class, $customerClientStub); // Act static::createClient()->request('GET', '/customers'); // Assert $this->assertResponseIsSuccessful(); $this->assertJsonContains(['@type' => 'Collection']); } ``` ## Available assertions ### HTTP response assertions ```php // Status codes $this->assertResponseIsSuccessful(); // 2xx status code $this->assertResponseStatusCodeSame(200); // Exact status code $this->assertResponseStatusCodeSame(201); // Created $this->assertResponseStatusCodeSame(204); // No content $this->assertResponseStatusCodeSame(400); // Bad request $this->assertResponseStatusCodeSame(401); // Unauthorized $this->assertResponseStatusCodeSame(403); // Forbidden $this->assertResponseStatusCodeSame(404); // Not found $this->assertResponseStatusCodeSame(422); // Validation error // Headers $this->assertResponseHasHeader('Content-Type'); $this->assertResponseHeaderSame('Content-Type', 'application/ld+json; charset=utf-8'); $this->assertResponseHeaderNotSame('X-Custom-Header', 'value'); // Content $this->assertResponseHasNoContent(); // Empty response body ``` ### JSON assertions ```php // Content matching $this->assertJsonContains(['email' => 'test@example.com']); $this->assertJsonContains(['@type' => 'Customer']); $this->assertJsonContains(['@type' => 'Collection']); // Array keys $responseData = $response->toArray(); $this->assertArrayHasKey('customerReference', $responseData); $this->assertArrayNotHasKey('password', $responseData); // Validation violations $this->assertJsonContains(['@type' => 'ConstraintViolationList']); $this->assertJsonContains([ 'violations' => [ ['propertyPath' => 'email'], ], ]); // Collection metadata $this->assertJsonContains(['totalItems' => 10]); $this->assertJsonContains(['view' => ['@id' => '/customers?page=1']]); ``` ### Custom API Platform assertions ```php // JSON-LD context $this->assertJsonContains(['@context' => '/contexts/Customer']); // Hydra collections $this->assertJsonContains(['hydra:totalItems' => 5]); $this->assertJsonContains(['hydra:member' => []]); // IRI matching $iri = $this->getIriFromResource($resource); $this->assertMatchesRegularExpression('~^/customers/[A-Z0-9\-]+$~', $iri); ``` ## Test data management ### Using Codeception helpers Create test data using your project's tester helpers: ```php // Create a customer $customerTransfer = $this->tester->haveCustomer([ 'email' => 'test@example.com', 'firstName' => 'John', 'lastName' => 'Doe', ]); // Create multiple customers for ($i = 1; $i <= 10; $i++) { $this->tester->haveCustomer([ 'email' => sprintf('customer%d@example.com', $i), ]); } ``` ### Cleanup strategies #### Automatic cleanup (default) The test kernel automatically cleans up after each test. No manual cleanup needed. #### Manual cleanup (when needed) ```php protected function tearDown(): void { // Custom cleanup logic $this->tester->cleanupCustomers(); parent::tearDown(); } ``` ## Testing different media types ### JSON-LD (default) ```php public function testJsonLdFormat(): void { static::createClient()->request('GET', '/customers', [ 'headers' => [ 'Accept' => 'application/ld+json', ], ]); $this->assertResponseHeaderSame('Content-Type', 'application/ld+json; charset=utf-8'); $this->assertJsonContains(['@context' => '/contexts/Customer']); } ``` ### JSON:API ```php public function testJsonApiFormat(): void { static::createClient()->request('GET', '/customers', [ 'headers' => [ 'Accept' => 'application/vnd.api+json', ], ]); $this->assertResponseHeaderSame('Content-Type', 'application/vnd.api+json; charset=utf-8'); $this->assertJsonContains(['data' => ['type' => 'Customer']]); } ``` ### HAL+JSON ```php public function testHalJsonFormat(): void { static::createClient()->request('GET', '/customers', [ 'headers' => [ 'Accept' => 'application/hal+json', ], ]); $this->assertResponseHeaderSame('Content-Type', 'application/hal+json; charset=utf-8'); $this->assertJsonContains(['_links' => ['self' => ['href' => '/customers']]]); } ``` ## Advanced testing patterns ### Testing with filters ```php public function testGivenFilterParamsWhenRetrievingCollectionThenFilteredResultsAreReturned(): void { // Arrange $this->tester->haveCustomer(['email' => 'active@example.com', 'status' => 'active']); $this->tester->haveCustomer(['email' => 'inactive@example.com', 'status' => 'inactive']); // Act static::createClient()->request('GET', '/customers?status=active'); // Assert $this->assertResponseIsSuccessful(); $responseData = static::createClient()->getResponse()->toArray(); $this->assertCount(1, $responseData['hydra:member']); } ``` ### Testing sorting ```php public function testGivenSortParamsWhenRetrievingCollectionThenSortedResultsAreReturned(): void { // Arrange $this->tester->haveCustomer(['lastName' => 'Zulu']); $this->tester->haveCustomer(['lastName' => 'Alpha']); $this->tester->haveCustomer(['lastName' => 'Bravo']); // Act static::createClient()->request('GET', '/customers?order[lastName]=asc'); // Assert $this->assertResponseIsSuccessful(); $responseData = static::createClient()->getResponse()->toArray(); $members = $responseData['hydra:member']; $this->assertEquals('Alpha', $members[0]['lastName']); $this->assertEquals('Bravo', $members[1]['lastName']); $this->assertEquals('Zulu', $members[2]['lastName']); } ``` ### Testing error scenarios ```php public function testGivenMalformedJsonWhenCreatingCustomerViaPostThenBadRequestIsReturned(): void { // Act static::createClient()->request('POST', '/customers', [ 'body' => '{invalid-json}', 'headers' => [ 'Content-Type' => 'application/json', ], ]); // Assert $this->assertResponseStatusCodeSame(400); } public function testGivenUnauthorizedRequestWhenAccessingProtectedResourceThen401IsReturned(): void { // Act static::createClient()->request('GET', '/customers/me'); // Assert $this->assertResponseStatusCodeSame(401); } ``` ## Running tests ### Run all project tests (slow, not recommended) ```bash docker/sdk cli vendor/bin/codecept run ``` ### Run specific test suite ```bash # Run Backend API tests only docker/sdk cli vendor/bin/codecept run -c path/to/codeception.yml -g BackendApi # Run Storefront API tests only docker/sdk cli vendor/bin/codecept run -c path/to/codeception.yml -g StorefrontApi ``` ## Codeception configuration ### Suite configuration Configure your test suite's `codeception.yml` to enable the necessary helpers: `tests/PyzTest/Glue/Customer/BackendApi/codeception.yml` ```yaml suite_namespace: PyzTest\Glue\Customer\BackendApi actor: BackendApiTester modules: enabled: - \SprykerTest\Shared\Testify\Helper\BootstrapHelper: applicationPluginProvider: class: Spryker\Glue\GlueBackendApiApplication\GlueBackendApiApplicationFactory method: getApplicationPlugins paths: tests: . data: ../../../../../_data support: _support output: ../../../../../_output settings: bootstrap: _bootstrap.php colors: true memory_limit: 1024M ``` **Key configuration points:** - **BootstrapHelper**: Provides application plugins for the test kernel. This is optional and can be omitted if your tests do not require application-level dependencies. - **suite_namespace**: Must match your test suite's PHP namespace - **actor**: The tester class name (for example, `BackendApiTester`, `StorefrontApiTester`) ### ApiPlatformHelper modes `ApiPlatformHelper` runs in one of two modes, selected in the suite's `codeception.yml`: ```yaml modules: enabled: - \SprykerTest\ApiPlatform\Helper\ApiPlatformHelper: mode: 'project' # default; or 'core' for module-level tests ``` | Mode | Use this when | Before suite | After suite | |---|---|---|---| | `project` (default) | Testing your own project's API resources end-to-end. | Validates that the project-generated resources in `src/Generated/Api/` exist. Skips generation. | Does nothing — the compiled container is preserved across runs for fast subsequent invocations. | | `core` | Testing the `ApiPlatform` module itself (or any module that ships its own schemas in isolation from a project). | Generates fresh resources into `tests/_data/Api/{ApiType}/`. Requires `apiType` to be set on the helper. | Removes the generated resources and clears the compiled test kernel cache so the next suite starts from a clean slate. | Use `project` mode for almost all real-world test suites — it is significantly faster because the compiled Symfony container is reused. Reach for `core` mode only when you intentionally want each suite to regenerate resources from scratch (typical when testing schema generation or a single module without a project around it). When using `core` mode, declare which API type the suite exercises so the helper knows what to generate: ```yaml modules: enabled: - \SprykerTest\ApiPlatform\Helper\ApiPlatformHelper: mode: 'core' apiType: 'Storefront' # or 'Backend' ``` ### Helper classes Create helper classes to manage test data: `tests/PyzTest/Glue/Customer/Helper/CustomerHelper.php` ```php <?php namespace PyzTest\Glue\Customer\Helper; use Codeception\Module; use Generated\Shared\Transfer\CustomerTransfer; use Pyz\Zed\Customer\Business\CustomerFacadeInterface; class CustomerHelper extends Module { public function haveCustomer(array $seed = []): CustomerTransfer { $customerTransfer = (new CustomerTransfer()) ->fromArray($seed, true) ->setEmail($seed['email'] ?? sprintf('customer-%s@example.com', uniqid())) ->setFirstName($seed['firstName'] ?? 'Test') ->setLastName($seed['lastName'] ?? 'Customer'); return $this->getCustomerFacade()->createCustomer($customerTransfer); } protected function getCustomerFacade(): CustomerFacadeInterface { return $this->getModule('\\PyzTest\\Shared\\Testify\\Helper\\Environment') ->getFacade('Customer'); } } ``` ## Best practices ### 1. Use descriptive test method names ```php // ✅ Good public function testGivenInvalidEmailWhenCreatingCustomerViaPostThenValidationErrorIsReturned(): void // ❌ Bad public function testCreate(): void ``` ### 2. Follow Arrange-Act-Assert pattern ```php public function testExample(): void { // Arrange - Set up test data and preconditions $data = ['email' => 'test@example.com']; // Act - Execute the operation being tested static::createClient()->request('POST', '/customers', ['json' => $data]); // Assert - Verify the results $this->assertResponseIsSuccessful(); } ``` ### 3. Test one thing per test ```php // ✅ Good - Tests one specific validation rule public function testGivenMissingEmailWhenCreatingCustomerThenValidationErrorIsReturned(): void { static::createClient()->request('POST', '/customers', ['json' => []]); $this->assertJsonContains(['violations' => [['propertyPath' => 'email']]]); } // ❌ Bad - Tests multiple unrelated things public function testCustomerCreation(): void { // Tests validation, creation, retrieval, update all in one test } ``` ### 4. Use meaningful test data ```php // ✅ Good $customerData = [ 'email' => 'john.doe@example.com', // Realistic email 'firstName' => 'John', // Realistic name 'lastName' => 'Doe', ]; // ❌ Bad $customerData = [ 'email' => 'a@b.c', // Not realistic 'firstName' => 'x', // Not meaningful 'lastName' => 'y', ]; ``` ### 5. Clean up test data appropriately ```php // For Backend API tests - use tester helpers for setup $customer = $this->tester->haveCustomer(['email' => 'test@example.com']); // Cleanup happens automatically via test kernel shutdown ``` ### 6. Test error cases ```php // Always test both success and failure scenarios public function testSuccessfulCreation(): void { /* ... */ } public function testValidationErrors(): void { /* ... */ } public function testDuplicateEmail(): void { /* ... */ } public function testNotFound(): void { /* ... */ } ``` ### 7. Use constants for repeated values ```php class CustomersBackendApiTest extends BackendApiTestCase { private const TEST_EMAIL = 'test@example.com'; private const TEST_FIRST_NAME = 'John'; public function testExample(): void { $data = [ 'email' => self::TEST_EMAIL, 'firstName' => self::TEST_FIRST_NAME, ]; // ... } } ``` ### 8. Group related tests ```php /** * @group PyzTest * @group Glue * @group Customer * @group BackendApi * @group CustomersBackendApiTest * @group ValidationTests */ class CustomersBackendApiTest extends BackendApiTestCase { // Run only validation tests: // vendor/bin/codecept run -g ValidationTests } ``` ## Troubleshooting ### Generated resources not found **Problem:** Test fails with "Class not found" for generated resource. **Solution:** 1. Verify autoload configuration in `composer.json`: ```json { "autoload-dev": { "psr-4": { "PyzTest\\": "tests/PyzTest/", "Generated\\TestApi\\": "tests/_data/Api/" } } } ``` 2. Run composer dump-autoload: ```bash docker/sdk cli composer dump-autoload ``` ### Test kernel boot failures **Problem:** Tests fail with kernel boot errors. **Solution:** Ensure your test case extends the correct base class: ```php // For Backend API use PyzTest\Shared\ApiPlatform\Test\BackendApiTestCase; class CustomersBackendApiTest extends BackendApiTestCase { // ... } // For Storefront API use PyzTest\Shared\ApiPlatform\Test\StorefrontApiTestCase; class CustomersStorefrontApiTest extends StorefrontApiTestCase { // ... } ``` ### Assertion failures with JSON-LD **Problem:** JSON assertions fail with `@context` or `@type` fields. **Solution:** Use JSON-LD specific assertions: ```php // ✅ Correct $this->assertJsonContains(['@type' => 'Customer']); $this->assertJsonContains(['@context' => '/contexts/Customer']); // ❌ Wrong $this->assertJsonContains(['type' => 'Customer']); ``` ### Tester helper not found **Problem:** `$this->tester` property shows as undefined. **Solution:** 1. Verify your tester class exists in the correct location 2. Check that the tester is properly type-hinted in your test: ```php class CustomersBackendApiTest extends BackendApiTestCase { protected BackendApiTester $tester; // Must be declared } ``` 3. Rebuild Codeception actors: ```bash docker/sdk cli vendor/bin/codecept build ``` ## Next steps - [API Platform Enablement](/docs/dg/dev/architecture/api-platform/enablement.html) - Creating API resources - [Resource Schemas](/docs/dg/dev/architecture/api-platform/resource-schemas.html) - Resource schema reference - [Validation Schemas](/docs/dg/dev/architecture/api-platform/validation-schemas.html) - Validation schema reference - [Troubleshooting](/docs/dg/dev/architecture/api-platform/troubleshooting.html) - Common issues and solutions - [Codeception Documentation](https://codeception.com/docs/Introduction) - Codeception framework docs - [API Platform Testing](https://api-platform.com/docs/symfony/testing/) - Official API Platform testing guide Tue, 19 May 2026 12:29:11 +0000 https://docs.spryker.com/docs/dg/dev/architecture/api-platform/testing.html https://docs.spryker.com/docs/dg/dev/architecture/api-platform/testing.html This document explains how to define API Platform resource schemas in Spryker. ## Schema file structure API Platform uses YAML files to define resource schemas. Resource schemas describe the structure, operations, and behavior of your API resources. ### Schema location Resource schemas must be placed in the `resources/api/{api-type}/` directory within your module: ```MARKDOWN src/ ├── Spryker/ │ └── {Module}/ │ └── resources/ │ └── api/ │ ├── storefront/ │ │ └── resource-name.resource.yml │ └── backend/ │ └── resource-name.resource.yml ├── SprykerFeature/ │ └── {Feature}/ │ └── resources/ │ └── api/ │ └── backend/ │ └── resource-name.resource.yml └── Pyz/ └── Glue/ └── {Module}/ └── resources/ └── api/ └── backend/ └── resource-name.resource.yml ``` ## CodeBucket resources API Platform supports CodeBucket-specific resource variants that are resolved at runtime based on the `APPLICATION_CODE_BUCKET` environment constant. This enables Code Bucket-specific API resources without requiring separate container compilations. ### CodeBucket schema file naming Resource schemas follow the pattern: `{resource-name}.resource.yml` Validation schemas follow the pattern: `{resource-name}.validation.yml` CodeBuckets are specified inside the schema files, not in the filename. ```MARKDOWN src/Pyz/Glue/StoresApi/resources/api/backend/ ├── stores.resource.yml # Resource schema (CodeBucket variants defined inside) └── stores.validation.yml # Validation schema (CodeBucket variants defined inside) ``` ### Generated class naming The generator creates classes following the pattern: `{ResourceName}{CodeBucket}{ApiType}Resource` | Schema File | CodeBucket (defined in file) | Generated Class | CODE_BUCKET Constant | |-------------|------------------------------|----------------|---------------------| | `stores.resource.yml` | None (base) | `StoresBackendResource` | Not present (base resource) | | `stores.resource.yml` | EU | `StoresEUBackendResource` | `'EU'` | | `stores.resource.yml` | AT | `StoresATBackendResource` | `'AT'` | ### How CodeBucket resolution works 1. **Schema definition**: Define CodeBucket variants inside schema files using `codeBucket: EU` 2. **Constant generation**: Generator adds `public const string CODE_BUCKET = 'EU';` to variant classes 3. **Runtime resolution**: System reads `APPLICATION_CODE_BUCKET` and selects matching resource class 4. **Graceful fallback**: If no matching variant exists, base resource is used ### URL consistency All CodeBucket variants share the same URL path, with the Code Bucket defined in the domain: - EU variant: `glue-backend.eu.spryker.local/stores` → `StoresEUBackendResource` - AT variant: `glue-backend.at.spryker.local/stores` → `StoresATBackendResource` - DE variant: `glue-backend.de.spryker.local/stores` → `StoresBackendResource` (or `StoresDEBackendResource` if variant exists) The URL path is identical (`/stores`), but the Code Bucket in the domain determines which resource variant is used. Only properties, validations, and business logic differ between variants. ### When to use CodeBucket resources Use CodeBucket variants when you need: - Code Bucket-specific properties (EU GDPR fields, tax rates) - Code Bucket-specific validation rules - Country-specific business logic - Feature variations per Code Bucket For a comprehensive guide including implementation examples, see [CodeBucket Support](/docs/dg/dev/architecture/api-platform/code-buckets.html). ## Resource schema syntax ### Minimal example ```yaml resource: name: Products shortName: products description: "Product resource" operations: - type: Get - type: GetCollection properties: id: type: integer writable: false identifier: true name: type: string ``` {% info_block infoBox "shortName convention" %} `shortName` is the JSON:API `type` field for the resource and is used as the public URL segment. Use **lowercase kebab-case**, plural for noun-style resources (`products`, `addresses`, `abstract-product-prices`) and singular for action-style endpoints (`catalog-search`, `cart-reorder`). Multi-word names are always hyphenated. This matches every shipped resource in the platform. {% endinfo_block %} ### Complete example with all options ```yaml # yaml-language-server: $schema=../../../../../vendor/spryker/api-platform/resources/schemas/api-resource-schema-v1.json resource: # Resource identification name: Customers # Internal name (used for schema merging) shortName: customers # URL name (becomes /customers); JSON:API type field description: "Customer resource" # OpenAPI description # State providers and processors provider: "Pyz\\Glue\\Customer\\Api\\Backend\\Provider\\CustomerBackendProvider" processor: "Pyz\\Glue\\Customer\\Api\\Backend\\Processor\\CustomerBackendProcessor" # Pagination configuration paginationEnabled: true paginationItemsPerPage: 10 paginationMaximumItemsPerPage: 100 paginationClientEnabled: true paginationClientItemsPerPage: true # Security security: "is_granted('ROLE_ADMIN')" securityPostDenormalize: "is_granted('EDIT', object)" # Operations operations: - type: Post # Create new resource - type: Get # Get single resource - type: GetCollection # Get collection with pagination - type: Put # Replace entire resource - type: Patch # Update partial resource - type: Delete # Delete resource # Relationships — see Relationships article for full reference includes: - relationshipName: addresses targetResource: CustomersAddresses uriVariableMappings: customerReference: customerReference # Properties properties: idCustomer: type: integer description: "The unique identifier of the customer." writable: false # Read-only property readable: true # Include in responses (default: true) email: type: string description: "The email address." required: true # Required for all operations openapiContext: example: "john@example.com" format: "email" firstName: type: string description: "First name." openapiContext: example: "John" minLength: 1 maxLength: 100 status: type: string description: "Customer status." openapiContext: example: "active" schema: enum: ["active", "inactive", "pending"] customerReference: type: string description: "Unique customer reference." writable: false identifier: true # Use as URL identifier instead of @id dateOfBirth: type: string description: "Date of birth." openapiContext: format: "date" example: "1990-01-01" isActive: type: boolean description: "Active status." default: true creditLimit: type: number description: "Credit limit." openapiContext: format: "float" example: 5000.00 ``` ## Property types ### Supported types | Type | PHP Type | Example | Description | |------|----------|---------|-------------| | `string` | `string` | `"John"` | Text values | | `integer` | `int` | `42` | Whole numbers | | `number` | `float` | `3.14` | Decimal numbers | | `boolean` | `bool` | `true` | True/false values | | `array` | `array` | `["a", "b"]` | Lists of values | | `object` | `object` | `{"key": "value"}` | Strictly typed nested objects | | `map` | `array` | `{"key": "value"}` | Free-shape associative payloads documented via `openapiContext`. Stored as PHP `array` and rendered as `type: object` in the OpenAPI specification. | | `mixed` | `mixed` | any | Use only when the payload genuinely has no fixed shape and cannot be described via `openapiContext`. | Use `map` when the payload is a structured JSON object whose schema you want to describe via `openapiContext` rather than a strongly typed PHP class. This is the recommended type whenever a request or response body is a JSON object with a known shape but no dedicated DTO class — it keeps the property typed as a simple `array` in PHP while still producing rich OpenAPI metadata and a working "Try Out" body in Swagger UI. See [Documenting nested properties for OpenAPI and Swagger UI](#documenting-nested-properties-for-openapi-and-swagger-ui) for the full pattern. ### Property attributes #### writable Controls if property can be sent in requests (POST/PUT/PATCH): ```yaml password: type: string writable: true # Can be sent in requests readable: false # Not included in responses ``` #### readable Controls if property is included in responses: ```yaml idCustomer: type: integer writable: false # Cannot be modified readable: true # Included in responses ``` #### identifier Marks property as URL identifier: ```yaml customerReference: type: string identifier: true # URL becomes /customers/{customerReference} ``` #### required Makes property mandatory (use validation schemas for detailed rules): ```yaml email: type: string required: true # Must be present ``` #### default Sets default value: ```yaml isActive: type: boolean default: true # Defaults to true if not provided ``` ## Documenting nested properties for OpenAPI and Swagger UI Many endpoints accept or return structured JSON payloads — for example, a payment initialization request that takes `payment`, `quote`, and `customer` sub-objects. Without explicit metadata, those payloads appear as opaque `object` entries in the OpenAPI document, which means: - The generated OpenAPI specification does not describe the child fields, their types, or which ones are required. - The Swagger UI "Try Out" button shows an empty request body, forcing consumers to read code or external documentation to discover the expected shape. The `map` property type combined with nested `openapiContext` entries closes both gaps. ### When to use this pattern Use this pattern when the request or response body is a structured JSON object whose schema you want to publish through OpenAPI, but you do not want to introduce a dedicated typed PHP class for it. Typical cases are: - Request payloads that aggregate fields from multiple transfer objects (for example, payment selection plus quote context). - PSP- or provider-specific response payloads whose shape varies by configuration. For payloads with a stable, strongly typed shape, prefer `type: object` so the generated PHP class enforces the structure at the language level. ### Pattern Combine `type: map` on the property with the following entries inside `openapiContext`: | Entry | Purpose | |-------|---------| | `properties` | Declares each child field with its own `type`, `description`, `format`, and `example`. Used by Swagger UI to render the field-by-field schema. | | `required` | Lists the child fields that must be present on a request. Drives the "required" markers in Swagger UI and the OpenAPI specification. | | `example` | A complete sample payload. This is the value Swagger UI prefills into the "Try Out" body, so consumers can execute the request immediately. | When the property is a `map`, the generator merges `'type' => 'object'` into the emitted `openapiContext`, so the property appears as an object — with the documented schema — in the OpenAPI document while staying as a plain PHP `array` in the generated resource class. ### Worked example The following extract is taken from `src/Spryker/PaymentsRestApi/resources/api/storefront/payments.resource.yml`. It shows three common shapes: a flat request object (`payment`), a request object with nested object children (`quote`), and a response-only object whose contents vary at runtime (`preOrderPaymentData`). ```yaml properties: payment: type: map writable: true readable: false required: true description: 'Payment selection for the pre-order initialization' openapiContext: required: ['paymentProviderName', 'paymentMethodName', 'amount'] properties: paymentProviderName: type: string example: 'DummyPayment' paymentMethodName: type: string example: 'Invoice' amount: type: integer description: 'Amount in minor units (cents)' example: 9999 example: paymentProviderName: 'DummyPayment' paymentMethodName: 'Invoice' amount: 9999 quote: type: map writable: true readable: false required: true description: 'Quote context required to initialize the payment' openapiContext: required: ['customer', 'billingAddress', 'currency'] properties: customer: type: object required: ['firstName', 'lastName', 'email'] properties: firstName: { type: string, example: 'Sonia' } lastName: { type: string, example: 'Wagner' } email: { type: string, format: email, example: 'sonia@acme.com' } billingAddress: type: object required: ['iso2Code'] properties: iso2Code: { type: string, example: 'DE' } currency: type: object required: ['code'] properties: code: { type: string, example: 'EUR' } example: customer: firstName: 'Sonia' lastName: 'Wagner' email: 'sonia@acme.com' billingAddress: iso2Code: 'DE' currency: code: 'EUR' preOrderPaymentData: type: map writable: false readable: true required: false description: 'PSP-specific response payload returned by the payment provider' openapiContext: example: transactionId: 'tx_abc123' redirectUrl: 'https://psp.example.com/pay/tx_abc123' ``` ### Read-only versus write-only payloads - **Write-only request payloads** (`writable: true`, `readable: false`) should declare `properties`, `required`, and `example`. The first two drive request validation and the generated OpenAPI schema; `example` makes the Swagger UI "Try Out" body usable without edits. - **Read-only response payloads** (`writable: false`, `readable: true`) only need `openapiContext.example` when the response shape is dynamic. If the response shape is fixed, prefer declaring `properties` (and optionally `required`) so consumers see the full schema. ### Validation note `openapiContext.required` controls only the OpenAPI documentation. If a request field must be enforced at runtime, add the matching constraint to the resource's validation schema — see [Validation Schemas](/docs/dg/dev/architecture/api-platform/validation-schemas.html). ## Automatic JSON:API request body examples For JSON:API endpoints (`application/vnd.api+json`), the generator automatically wraps property-level examples in the JSON:API envelope (`data.type` + `data.attributes`) when it builds the OpenAPI request body. You define examples once per property; the generator assembles the envelope for every write operation. Given: ```yaml resource: name: Customers shortName: customers # becomes the JSON:API "type" field properties: email: type: string writable: true openapiContext: example: "john@example.com" firstName: type: string writable: true openapiContext: example: "John" idCustomer: type: integer writable: false # excluded from request body example openapiContext: example: 42 ``` …the generated OpenAPI request body for `POST`, `PATCH`, and `PUT` operations is: ```json { "data": { "type": "customers", "attributes": { "email": "john@example.com", "firstName": "John" } } } ``` Rules the generator applies: - The `shortName` value becomes the `type` field. - Only **writable** properties are included — anything marked `writable: false` is filtered out (so identifiers and timestamps do not appear in the request example). - Properties without an `openapiContext.example` are omitted from the example body. - If no writable property has an example, no `requestBody` example is emitted at all — the operation appears without a prefilled "Try Out" body. If you need a custom request body example that does not match this shape, override it at the operation level — see [Operations](#operations). ## Operations Define which HTTP operations are available for the resource: ```yaml operations: - type: Get # GET /customers/{id} - type: GetCollection # GET /customers - type: Post # POST /customers - type: Put # PUT /customers/{id} - type: Patch # PATCH /customers/{id} - type: Delete # DELETE /customers/{id} ``` The operation names map to HTTP methods: - `post` → POST (create) - `get` → GET (single resource) - `getCollection` → GET (collection) - `put` → PUT (replace) - `patch` → PATCH (update) - `delete` → DELETE (remove) ## Pagination API Platform provides built-in pagination for collection endpoints (`GetCollection`). You can configure pagination behavior per resource using YAML schema options. ### Pagination options | Option | Type | Description | |--------|------|-------------| | `paginationEnabled` | `boolean` | Enables or disables pagination for this resource. When `false`, `GetCollection` returns all results without pagination. Default: inherits from global configuration. | | `paginationItemsPerPage` | `integer` | Number of items returned per page. Overrides the global default. | | `paginationMaximumItemsPerPage` | `integer` | Maximum number of items a client can request per page via `itemsPerPage` query parameter. Prevents clients from requesting excessively large pages. | | `paginationClientEnabled` | `boolean` | Allows clients to enable or disable pagination via the `pagination` query parameter (for example, `?pagination=false`). | | `paginationClientItemsPerPage` | `boolean` | Allows clients to set the number of items per page via the `itemsPerPage` query parameter (for example, `?itemsPerPage=50`). | The global default for `paginationItemsPerPage` is defined in the project's `api_platform.php` configuration file. To override it for a specific resource, set `paginationItemsPerPage` in the resource schema. ### Minimal pagination example ```yaml resource: name: Products shortName: products paginationEnabled: true paginationItemsPerPage: 10 operations: - type: GetCollection ``` ### Full pagination example ```yaml resource: name: Products shortName: products paginationEnabled: true paginationItemsPerPage: 20 paginationMaximumItemsPerPage: 100 paginationClientEnabled: true paginationClientItemsPerPage: true operations: - type: GetCollection - type: Get ``` With this configuration, clients can use the following query parameters: ```bash # Default pagination (20 items per page) GET /products # Navigate to page 3 GET /products?page=3 # Request 50 items per page (up to maximum of 100) GET /products?itemsPerPage=50 # Disable pagination to get all results GET /products?pagination=false ``` ### Generated output The pagination options are rendered as named parameters in the `#[ApiResource]` attribute: ```php #[ApiResource( operations: [new GetCollection(), new Get()], shortName: 'products', provider: ProductsBackendProvider::class, paginationItemsPerPage: 20, paginationEnabled: true, paginationMaximumItemsPerPage: 100, paginationClientEnabled: true, paginationClientItemsPerPage: true )] ``` ### Provider requirements For pagination to work, your Provider must return a `TraversablePaginator` instance for collection operations: ```php use ApiPlatform\State\Pagination\TraversablePaginator; return new TraversablePaginator( new \ArrayObject($resources), $currentPage, $itemsPerPage, $totalItems ); ``` If `paginationEnabled` is `true` but the Provider returns a plain array, API Platform wraps the result in a `PartialPaginatorInterface`, which may not include total count or page metadata. ### Global pagination defaults Global pagination defaults can be configured in the application configuration file. Per-resource settings override the global defaults. See [API Platform Configuration](/docs/dg/dev/architecture/api-platform/configuration.html) for details. ## Relationships Define relationships between resources to enable including related resources via the `?include=` query parameter. ### includes section Declares what relationships this resource can include. Each entry describes one relationship that clients can request via the `?include=` query parameter on this resource. ```yaml includes: - relationshipName: addresses targetResource: CustomersAddresses uriVariableMappings: customerReference: customerReference ``` **Entry fields:** | Field | Required | Description | |-------|----------|-------------| | `relationshipName` | Yes | Name used in the `?include=` parameter and as the JSON:API relationship key. | | `targetResource` | Yes | The `name` of the included resource as declared in its `resource.yml` (for example, `CustomersAddresses`). | | `uriVariableMappings` | Conditional | Maps properties from the parent resource to the URI variables of the included resource. Required when the included resource is routed by URI variables. Format: `parentProperty: childUriVariable`. | | `uriTemplate` | Optional | Explicit URI template for the included resource when it has multiple operations and the relationship must target a specific path (for example, `/abstract-products/{abstractProductSku}/abstract-product-prices`). | | `resolverClass` | Optional | Fully qualified class name of a relationship resolver. Use when the relationship cannot be expressed via URI variables — the resolver receives the parent resources and the request context, and returns the related resources directly. When `resolverClass` is set, `uriVariableMappings` and `uriTemplate` are not used for routing. | #### URI-variable mapping example For relationships routed by sub-resource URLs, map parent properties to child URI variables: ```yaml includes: - relationshipName: abstract-product-prices targetResource: AbstractProductPrices uriTemplate: /abstract-products/{abstractProductSku}/abstract-product-prices uriVariableMappings: sku: abstractProductSku ``` #### Resolver-based example For relationships whose targets cannot be derived from URI variables (for example, derived from order state or aggregated across multiple sources), reference a resolver class: ```yaml includes: - relationshipName: order-shipments targetResource: OrderShipments resolverClass: Spryker\Glue\ShipmentsRestApi\Api\Storefront\Relationship\OrderShipmentsRelationshipResolver ``` ### includableIn section Declares where this resource can be included: ```yaml includableIn: - resource: Customers relationshipName: addresses uriVariableMappings: customerReference: customerReference ``` Both declarations must match for validation to pass. **Further reading:** [Relationships](/docs/dg/dev/architecture/api-platform/relationships.html) — full reference for declaring, resolving, and troubleshooting relationships between API Platform resources. ## Resource generation process ### Generation workflow The resource generation process is organized into distinct phases, each producing result objects for comprehensive error tracking and reporting: ```MARKDOWN 1. Preparation Phase ↓ 2. Schema Parsing Phase → ParseResult - Load validation schemas - Parse validation rules - Load resource schemas - Parse resource definitions ↓ 3. Schema Merging Phase → MergeResult - Merge schemas (Core → Feature → Project) - Track contributing source files ↓ 4. Validation Phase → ValidationResult - Validate merged schemas - Apply validation rules ↓ 5. Code Generation Phase - Generate PHP resource classes - Write files to output directory ↓ 6. Cache Update ``` ### Result objects Each phase produces result objects that encapsulate both successful outcomes and failures: - **ParseResult**: Contains grouped schemas and tracks failed validation files and schema files that could not be parsed - **MergeResult**: Contains successfully merged schemas and tracks resources that failed to merge - **ValidationResult**: Contains validated schemas and tracks resources that failed validation with detailed error messages This structured approach ensures that errors in one resource do not block the generation of other valid resources, and provides clear feedback about what succeeded and what failed. ### Multi-layer schema merging Spryker automatically merges schemas from multiple layers: **Core layer** (lowest priority): **vendor/spryker/customer/resources/api/backend/customer.resource.yml** ```yaml resource: name: Customers properties: email: type: string firstName: type: string ``` **Feature layer** (medium priority): **src/SprykerFeature/CRM/resources/api/backend/customer.resource.yml** ```yaml resource: name: Customers properties: phone: type: string # Added property ``` **Project layer** (highest priority): **src/Pyz/Glue/Customer/resources/api/backend/customer.resource.yml** ```yaml resource: name: Customers properties: email: required: true # Override core definition customField: type: string # Project-specific field ``` **Merged result:** ```yaml resource: name: Customers properties: email: type: string required: true # From project layer firstName: type: string # From core layer phone: type: string # From feature layer customField: type: string # From project layer ``` ### Generated resource class The generator creates a complete PHP class with API Platform attributes: ```php <?php declare(strict_types=1); namespace Generated\Api\Backend; use ApiPlatform\Metadata\ApiResource; use ApiPlatform\Metadata\ApiProperty; use Symfony\Component\Validator\Constraints as Assert; use ApiPlatform\Metadata\Get; use ApiPlatform\Metadata\GetCollection; use ApiPlatform\Metadata\Post; use ApiPlatform\Metadata\Patch; use ApiPlatform\Metadata\Delete; #[ApiResource( operations: [new Post(), new Get(), new GetCollection(), new Patch(), new Delete()], shortName: 'customers', provider: CustomerBackendProvider::class, processor: CustomerBackendProcessor::class, paginationItemsPerPage: 10, paginationEnabled: true, paginationMaximumItemsPerPage: 100, paginationClientEnabled: true, paginationClientItemsPerPage: true )] final class CustomersBackendResource { #[ApiProperty(writable: false)] public ?int $idCustomer = null; #[ApiProperty(openapiContext: ['example' => 'john@example.com'])] #[Assert\NotBlank(groups: ['customers:create'])] #[Assert\Email(groups: ['customers:create'])] public ?string $email = null; #[ApiProperty(identifier: true, writable: false)] public ?string $customerReference = null; public ?bool $isActive = true; // Getters, setters, toArray(), fromArray() methods... } ``` ## Debugging schemas ### Debug commands ```bash # List all resources docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug --list # Show specific resource docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug customers --api-type=backend # Show merged schema docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug customers --api-type=backend --show-merged # Show contributing source files docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug customers --api-type=backend --show-sources # Validate schemas without generating docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only ``` ### Common schema errors The generator validates schemas and provides detailed error messages: ```bash # Missing required fields Error: Resource "customers" is missing required field "name" # Invalid operation type Error: Invalid operation type "INVALID". Must be one of: Get, Post, Put, Patch, Delete, GetCollection # Invalid property type Error: Property "age" has invalid type "int". Must be one of: string, integer, number, boolean, array, object # Provider class not found Error: Provider class "Pyz\Glue\Customer\Api\Backend\Provider\MissingProvider" does not exist ``` ## Advanced schema features ### Custom URL paths Operations support `uriTemplate` and `uriVariables` to define custom URL paths, including sub-resource URLs like `/customers/{customerReference}/addresses`. #### Sub-resource with full CRUD Define a child resource with nested URLs by adding `uriTemplate` and `uriVariables` to each operation: **customers-addresses.resource.yml** ```yaml resource: name: CustomersAddresses shortName: customers-addresses operations: - type: GetCollection uriTemplate: '/customers/{customerReference}/addresses' uriVariables: customerReference: toProperty: 'customer' fromClass: CustomersStorefrontResource - type: Get uriTemplate: '/customers/{customerReference}/addresses/{uuid}' uriVariables: customerReference: toProperty: 'customer' fromClass: CustomersStorefrontResource uuid: fromClass: CustomersAddressesStorefrontResource - type: Post uriTemplate: '/customers/{customerReference}/addresses' uriVariables: customerReference: toProperty: 'customer' fromClass: CustomersStorefrontResource ``` **`uriVariables` properties:** - `fromClass`: The generated resource class the variable originates from - `toProperty`: The property on the current resource that links to the parent resource #### Action-style sub-resource For single-action endpoints nested under a parent resource: **customers-confirm-registration.resource.yml** ```yaml resource: name: CustomersConfirmRegistration shortName: customers-confirm-registration operations: - type: Post uriTemplate: /customers/{customerReference}/confirm-registration ``` For more details on `uriTemplate`, `uriVariables`, and sub-resource patterns, see the [API Platform sub-resources documentation](https://api-platform.com/docs/core/subresources/). ### Security expressions Security expressions protect resources and operations using [Symfony's ExpressionLanguage](https://symfony.com/doc/current/security/expressions.html). They require the SecurityBundle to be configured. See [How to integrate API Platform Security](/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html) for setup instructions. {% info_block infoBox "Where roles come from" %} Roles like `ROLE_CUSTOMER` in security expressions come from OAuth scopes that are automatically mapped to Symfony roles. The mapping convention is as follows: a scope name is uppercased and prefixed with `ROLE_`. For example, the `customer` scope becomes `ROLE_CUSTOMER`. Scopes are provided by scope provider plugins registered in `OauthDependencyProvider::getScopeProviderPlugins()`. The following table lists the out-of-the-box scope provider plugins and the scopes they provide: | Plugin | Scopes | |--------|--------| | `CustomerOauthScopeProviderPlugin` | `customer` | | `CompanyUserOauthScopeProviderPlugin` | `company_user` | | `AgentOauthScopeProviderPlugin` | `agent` | | `CustomerImpersonationOauthScopeProviderPlugin` | `customer_impersonation`, `customer` | | `UserOauthScopeProviderPlugin` | `user`, plus UserType sub-plugins | | `WarehouseOauthScopeProviderPlugin` | `warehouse` | For details on how the mapping works, see [Security — Roles and OAuth scope mapping](/docs/dg/dev/architecture/api-platform/security.html). For instructions on setting up scopes, see [Integrate the authorization scopes](/docs/integrations/spryker-glue-api/backend-api/integrate-backend-api/integrate-the-authorization-scopes.html). {% endinfo_block %} Three types of security expressions are supported: | Expression | Evaluated | Use case | When to use | |-----------|-----------|----------|-------------| | `security` | Before the request is processed | Check user roles or authentication status | For role or authentication checks that do not depend on the request body. | | `securityPostDenormalize` | After the request body is deserialized | Check authorization based on submitted data | When authorization depends on the deserialized resource `object`, for example, to verify the user owns the resource being modified. | | `securityPostValidation` | After validation passes | Check authorization based on validated data | When authorization depends on validated data, for example, to verify a value is within the user's authorized limit after validation confirms the data is structurally correct. | #### Resource-level security Applies to all operations on the resource: ```yaml resource: name: Customers shortName: customers security: "is_granted('ROLE_USER')" ``` #### Operation-level security Applies to a specific operation, overriding resource-level security: ```yaml resource: name: Customers shortName: customers operations: - type: Post # No security — public registration - type: Get security: "is_granted('ROLE_USER')" - type: Patch security: "is_granted('ROLE_USER')" ``` #### Post-denormalize security Evaluated after the request body has been deserialized. The `object` variable contains the resource instance: ```yaml resource: name: Orders shortName: orders security: "is_granted('ROLE_USER')" securityPostDenormalize: "is_granted('EDIT', object)" ``` {% info_block infoBox "Custom voter attributes" %} `EDIT` in the example is a **custom voter attribute** — it is an application-defined string, not a built-in Symfony or Spryker constant. For `is_granted('EDIT', object)` to work, you must register a custom Symfony [Voter](https://symfony.com/doc/current/security/voters.html) that supports the `EDIT` attribute and implements the authorization logic, for example, checking that the authenticated user owns the resource. Use `securityPostDenormalize` when the authorization decision depends on the **submitted request data** (the deserialized `object`), such as verifying resource ownership. {% endinfo_block %} #### Post-validation security Evaluated after validation has passed: ```yaml resource: name: Payments shortName: payments securityPostValidation: "is_granted('PROCESS', object)" ``` {% info_block infoBox "Custom voter attributes" %} `PROCESS` in the example is a **custom voter attribute** — it is an application-defined string, not a built-in Symfony or Spryker constant. For `is_granted('PROCESS', object)` to work, you must register a custom Symfony [Voter](https://symfony.com/doc/current/security/voters.html) that supports the `PROCESS` attribute. Use `securityPostValidation` when the authorization decision depends on **validated data**, for example, to verify a payment amount is within the user's authorized limit after validation confirms the data is structurally correct. {% endinfo_block %} For detailed information about the authentication flow, role mapping, and accessing the authenticated user in providers, see [Security](/docs/dg/dev/architecture/api-platform/security.html). ## Generation commands ### Basic generation ```bash # Generate all configured API types docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate # Generate specific API type docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate backend docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue api:generate storefront # Generate with options docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --dry-run # Preview without writing docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --validate-only # Only validate schemas docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate --resource=customers # Generate single resource ``` ### Output ```bash Generating API resources for ApiType: backend Discovering schema files... Validating schemas... OK Merging schemas... OK Generating resources: 10/10 [============================] 100% Generated: 10 file(s) Cache updated Done! ``` ## Schema validation rules The generator enforces these rules: ### Required fields Every resource must have: - `name` - Internal resource name - `shortName` - URL-friendly name - At least one `operation` - At least one `property` ### Valid operation types Only these operation types are allowed: - `Get` - Retrieve single resource - `GetCollection` - Retrieve collection - `Post` - Create resource - `Put` - Replace entire resource - `Patch` - Update partial resource - `Delete` - Delete resource ### Valid property types Only these property types are allowed: - `string` - `integer` - `number` - `boolean` - `array` - `object` - `map` - `mixed` ### Provider/Processor validation - Provider/Processor classes must exist - Classes must implement correct interfaces - Namespaces must be valid PHP namespaces ## Best practices ### 1. Use semantic naming ```yaml # ✅ Good resource: name: Customers # PascalCase plural — used for schema merging shortName: customers # lowercase kebab-case plural — JSON:API type + URL segment # ✅ Good — multi-word resource: name: AbstractProductPrices shortName: abstract-product-prices # ❌ Bad — wrong shortName casing/form resource: name: Customers shortName: Customer # Should be lowercase plural # ❌ Bad — abbreviated, unclear resource: name: CustomerData shortName: cust ``` ### 2. Document all properties ```yaml # ✅ Good email: type: string description: "The customer's email address used for login and notifications" # ❌ Bad email: type: string ``` ### 3. Leverage schema merging Core — define base properties: **src/Spryker/Customer/resources/api/backend/customer.resource.yml** ```yaml resource: name: Customers properties: email: type: string ``` Project — only override what is needed: **src/Pyz/Glue/Customer/resources/api/backend/customer.resource.yml** ```yaml resource: name: Customers properties: email: required: true # ← Only the difference ``` ### 4. Use readable/writable correctly ```yaml # Read-only fields (IDs, timestamps) idCustomer: type: integer writable: false # Write-only fields (passwords) password: type: string readable: false # Read-write fields (normal data) email: type: string writable: true readable: true ``` ## Next steps - [API Platform](/docs/dg/dev/architecture/api-platform.html) - Architecture overview - [Validation Schemas](/docs/dg/dev/architecture/api-platform/validation-schemas.html) - Define validation rules - [CodeBucket Support](/docs/dg/dev/architecture/api-platform/code-buckets.html) - Code Bucket-specific resources - [API Platform Enablement](/docs/dg/dev/architecture/api-platform/enablement.html) - Creating resources - [API Platform Testing](/docs/dg/dev/architecture/api-platform/testing.html) - Writing and running tests - [Troubleshooting](/docs/dg/dev/architecture/api-platform/troubleshooting.html) - Common issues - [API Platform Documentation](https://api-platform.com/docs/) - Official API Platform docs Tue, 19 May 2026 12:29:11 +0000 https://docs.spryker.com/docs/dg/dev/architecture/api-platform/resource-schemas.html https://docs.spryker.com/docs/dg/dev/architecture/api-platform/resource-schemas.html The API Platform relationship system enables resources to include related resources via the `?include=` query parameter in JSON:API format. ## Quick start ### 1. Define relationships in parent resource Add an `includes` section to your parent resource YAML: ```yaml # src/Spryker/Customer/resources/api/storefront/customers.resource.yml resource: name: Customers shortName: customers includes: - relationshipName: addresses targetResource: CustomersAddresses uriVariableMappings: customerReference: customerReference ``` ### 2. Define reverse relationship in child resource Add an `includableIn` section to your child resource YAML: ```yaml # src/Spryker/Customer/resources/api/storefront/customers-addresses.resource.yml resource: name: CustomersAddresses shortName: customers-addresses includableIn: - resource: Customers relationshipName: addresses uriVariableMappings: customerReference: customerReference ``` Both declarations must match for validation to pass. ### 3. Regenerate container ```bash docker/sdk testing -x GLUE_APPLICATION=GLUE_STOREFRONT glue cache:clear ``` ### 4. Use relationships ```bash # Single include GET /customers/customer--35?include=addresses # Multiple includes GET /customers/customer--35?include=addresses,orders ``` ## Configuration reference ### includes section Declares what relationships this resource can include. **Required properties:** - `relationshipName`: Name used in `?include=` parameter (for example, `addresses`) - `targetResource`: Name of the resource to include (for example, `CustomersAddresses`) **Optional properties:** - `uriVariableMappings`: Maps properties from parent to child provider URI variables **Example:** ```yaml includes: - relationshipName: addresses targetResource: CustomersAddresses uriVariableMappings: customerReference: customerReference ``` ### includableIn section Declares where this resource can be included. **Required properties:** - `resource`: Name of the parent resource - `relationshipName`: Must match parent's includes declaration **Optional properties:** - `uriVariableMappings`: Must match parent's includes declaration **Example:** ```yaml includableIn: - resource: Customers relationshipName: addresses uriVariableMappings: customerReference: customerReference ``` ## URI variable mapping URI variable mapping passes context from parent resource to child provider. **Example flow:** 1. Parent resource (Customer) has property `customerReference = 'DE--123'` 2. Configuration maps `customerReference: customerReference` 3. Child provider receives `['customerReference' => 'DE--123']` in URI variables 4. Child provider uses this to filter results **Multiple mappings:** ```yaml uriVariableMappings: customerReference: customerReference storeId: storeId locale: locale ``` ## Auto-generated properties When you define an `includes` relationship, the corresponding property is automatically generated with these defaults: | Attribute | Value | Rationale | |-----------|-------|-----------| | `type` | `array` | Relationships are collections | | `writable` | `false` | Relationships are read-only | | `readable` | `true` | Must be readable for responses | | `required` | `false` | Relationships are optional | | `description` | `"Related {targetResource} resources"` | Auto-generated description | You can override defaults by manually defining the property: ```yaml properties: addresses: type: array writable: false readable: true required: false description: "Customer billing and shipping addresses" ``` ## Validation The system validates relationships during code generation: **Bi-directional consistency:** - Parent's `includes` must match child's `includableIn` - Relationship names must match - URI variable mappings must match **Resource existence:** - Target resource must exist - Referenced properties should exist **Example error:** ```text Validation Error in customers.resource.yml: - includes[0].targetResource: Resource "CustomersAddresses" declares includableIn for "Customers" but uses different relationshipName "customerAddresses". Expected: "addresses" ``` ## Response format **Request:** ```http GET /customers/customer--35?include=addresses ``` **Response:** ```json { "data": { "type": "customers", "id": "customer--35", "attributes": { "email": "john@example.com", "firstName": "John" }, "relationships": { "addresses": { "data": [ {"type": "addresses", "id": "addr-123"}, {"type": "addresses", "id": "addr-456"} ] } } }, "included": [ { "type": "addresses", "id": "addr-123", "attributes": { "address1": "123 Test St", "city": "Test City" } }, { "type": "addresses", "id": "addr-456", "attributes": { "address1": "456 Other St", "city": "Other City" } } ] } ``` ## How it works 1. **RelationshipProviderDecorator** wraps all providers automatically 2. Parses `?include=` parameter from request 3. **ApiPlatformRelationshipResolver** loads relationships via container configuration 4. Maps URI variables from parent to child 5. Calls child provider with mapped variables 6. **JsonApiRelationshipNormalizer** builds JSON:API response with `relationships` and `included` sections Providers require no code changes - the system works automatically through decoration. ## Custom relationship resolvers The default provider-based resolution maps URI variables from the parent resource to the child provider. When that is not enough — for example, the related data lives on the parent's `context` payload, is aggregated from several sources, or needs custom denormalization — declare a resolver class instead. Reference the resolver in the parent's `includes` entry via `resolverClass`. When `resolverClass` is set, `uriVariableMappings` and `targetResource` are not used for routing; the resolver class is invoked directly with the parent resources and request context: ```yaml # src/Spryker/OrdersRestApi/resources/api/storefront/orders.resource.yml resource: name: Orders shortName: orders includes: - relationshipName: order-amendments targetResource: OrderAmendments resolverClass: Spryker\Glue\OrderAmendmentsRestApi\Api\Storefront\Relationship\OrderAmendmentsRelationshipResolver ``` The resolver class must implement `Spryker\ApiPlatform\Relationship\RelationshipResolverInterface`. In practice, extend `Spryker\ApiPlatform\Relationship\AbstractRelationshipResolver`, which gives you helpers for accessing the request, locale, store, and customer transfers: ```php namespace Spryker\Glue\OrderAmendmentsRestApi\Api\Storefront\Relationship; use Generated\Api\Storefront\OrderAmendmentsStorefrontResource; use Spryker\ApiPlatform\Relationship\AbstractRelationshipResolver; use Spryker\Service\Serializer\SerializerServiceInterface; class OrderAmendmentsRelationshipResolver extends AbstractRelationshipResolver { public function __construct(protected SerializerServiceInterface $serializer) { } /** * @return array<\Generated\Api\Storefront\OrderAmendmentsStorefrontResource> */ protected function resolveRelationship(): array { $resources = []; foreach ($this->getParentResources() as $orderResource) { $contextData = $orderResource->context ?? null; $amendmentData = is_array($contextData) && isset($contextData['salesOrderAmendment']) ? $contextData['salesOrderAmendment'] : null; if (!is_array($amendmentData) || $amendmentData === []) { continue; } $resources[] = $this->serializer->denormalize( $amendmentData, OrderAmendmentsStorefrontResource::class, ); } return $resources; } } ``` The `RelationshipConfigurationPass` compiler pass registers the class as an autowired public service automatically — no manual service definition is required. If the referenced class does not exist when the container compiles, the relationship is silently skipped and a compiler log entry is emitted. Use a custom resolver when: - The related data is already attached to the parent (for example, embedded in a transfer's `context` array) and a separate child provider would re-fetch it unnecessarily. - The relationship aggregates data from several sources that no single provider exposes. - The link from parent to child cannot be expressed as a simple property-to-URI-variable mapping. ## Performance Relationships are resolved per parent resource. For a collection of N parent resources with an `?include=` request, the child provider is called N times — one call per parent — which can produce an N+1 query pattern if the child provider hits the database per call. When you expect collection endpoints to be requested with `?include=`, optimize the child provider: - **Batch internally**: have the child provider detect repeated single-key lookups and coalesce them into one underlying query. For example, accept a `customerReference` URI variable but maintain an in-request cache of previously fetched results. - **Paginate the parent**: keep parent collection page sizes small (`paginationItemsPerPage`) so the per-include cost stays bounded. - **Profile real traffic**: enable Doctrine query logging or use Blackfire/Xdebug to confirm the N+1 hypothesis before optimizing — sometimes the parent's own query dominates and the includes are negligible. ## Troubleshooting ### Relationships are not returned The `?include=` parameter is silently ignored or returns no `relationships` block. Run through the following checks in order: 1. **Clear the cache.** Relationship configuration is built into the compiled container; YAML changes do not take effect until the container is rebuilt. ```bash docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue cache:clear ``` 2. **Confirm the parent declares the relationship.** Runtime resolution only reads `includes` on the parent — that declaration must be present and the names/`uriVariableMappings` must match what the request uses. A matching `includableIn` on the child is optional but recommended for discoverability; it does not affect runtime behavior. See the [Configuration reference](#configuration-reference). 3. **Inspect the compiled relationship registry.** API Platform exposes the merged configuration as a container parameter: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue debug:container --parameter=api_platform.relationships ``` The output lists every registered relationship keyed by `{parentResource}.{relationshipName}` (for example, `customers.addresses`). If your relationship is missing, the YAML was not picked up — re-check file location and run `api:generate`. 4. **Verify the child provider is registered.** The child resource needs a provider that API Platform can resolve: ```bash docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue debug:container | grep <ChildProviderClass> ``` ### Validation error: bi-directional consistency Resource generation fails with an error like: ```text Validation Error in customers.resource.yml: - includes[0].targetResource: Resource "CustomersAddresses" declares includableIn for "Customers" but uses different relationshipName "customerAddresses" Expected: "addresses" ``` The parent's `includes[].relationshipName` and the child's `includableIn[].relationshipName` must be identical strings. The same applies to `uriVariableMappings` — every mapping declared on the parent must appear on the child with the same source/target names. ### `relationships` block is present but `data` is empty The relationship is wired up but no related resources come back. 1. **The child provider is returning `null` or `[]`.** Call the child provider directly (or hit its standalone collection endpoint with the same URI variable values) to confirm it returns data. 2. **URI variable mapping does not produce a value.** A property on the parent that resolves to `null` is omitted from the URI variables passed to the child — verify the mapped property is populated on every parent resource in the response. Use `api:debug <resource> --show-merged` to confirm the property is declared. 3. **The child filters too aggressively.** Inspect the child provider's filtering logic with the URI variable values produced by the mapping. ### Invalid include names are ignored Unknown values in `?include=` (for example, a typo or a relationship the parent does not declare) are silently dropped — the response succeeds without that relationship and no error is raised. If a deployment appears to lose a relationship after a release, suspect a typo or a missing `includableIn` in the child before assuming a runtime failure. Tue, 19 May 2026 12:29:11 +0000 https://docs.spryker.com/docs/dg/dev/architecture/api-platform/relationships.html https://docs.spryker.com/docs/dg/dev/architecture/api-platform/relationships.html This guide shows how to enable IDE support for the YAML files that define API Platform resources (`*.resource.yml`) and their validation rules (`*.validation.yml`). Once configured, your IDE provides: - **Autocomplete** for resource properties, operation types, and validation constraints. - **Real-time validation** against the JSON Schema, flagging invalid configurations as you type. - **Inline documentation** for every property and attribute. - **Type safety**: values are checked against the declared types. ## Prerequisites The `ApiPlatform` module ships the canonical JSON Schema at: ```text vendor/spryker/api-platform/resources/schemas/api-resource-schema-v1.json ``` A hosted copy is also available at `https://static.spryker.com/api-resource-schema-v1.json`. ## Configure PHPStorm PHPStorm has built-in JSON Schema support — no plugin is required. 1. Open **Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings**. 2. Click the **+** to add a new mapping with: - **Name:** `Spryker API Resource Schema` - **Schema file or URL:** `$PROJECT_DIR$/vendor/spryker/api-platform/resources/schemas/api-resource-schema-v1.json` (or the hosted URL above). - **Schema version:** `JSON Schema version 7` 3. Under **File path pattern**, add `**/resources/api/*/*.resource.yml`. Add additional patterns if your project keeps resource YAMLs in other locations. 4. Apply and open any `*.resource.yml` file. Typing `resource:` should now produce autocomplete suggestions. Press `Ctrl+Q` (Windows/Linux) or `F1` (macOS) on any property to see its documentation. ## Configure VSCode VSCode requires the [Red Hat YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml). 1. Install the extension from the Extensions panel (`Ctrl+Shift+X` / `Cmd+Shift+X`). 2. Add the schema mapping to your project's `.vscode/settings.json`: ```json { "yaml.schemas": { "./vendor/spryker/api-platform/resources/schemas/api-resource-schema-v1.json": [ "**/resources/api/*/*.resource.yml" ] } } ``` 3. Reload the window (`Developer: Reload Window` from the command palette) and open a `*.resource.yml` file. Hover over any property to see its documentation; invalid values are underlined. {% info_block infoBox "Workspace settings vs. user settings" %} Project-level `.vscode/settings.json` is recommended so the configuration travels with the repository. The same `yaml.schemas` block also works in user settings if you prefer a global setup. {% endinfo_block %} ## Per-file schema reference You can also pin the schema inline at the top of any YAML file with the `yaml-language-server` directive. This is useful for one-off files that live outside the configured patterns: ```yaml # yaml-language-server: $schema=../../../../../vendor/spryker/api-platform/resources/schemas/api-resource-schema-v1.json resource: name: Customers shortName: customers description: Customer resource for the storefront API operations: - type: Get - type: GetCollection properties: idCustomer: type: integer description: The unique identifier identifier: true writable: false ``` The path is relative to the YAML file's location. Adjust the depth (`../`) accordingly, or use the hosted URL if your environment can reach it. ## Quick reference The JSON Schema covers the full resource and validation surface. The most common fields: ### Resource root | Field | Required | Description | |---|---|---| | `shortName` | yes | Resource identifier used in URLs. | | `name` | no | Full resource name (defaults to `shortName`). | | `description` | no | Human-readable description. | | `operations` | yes | One or more operations exposed by the resource. | | `properties` | yes | The resource's properties. | | `provider` | no | Fully qualified Provider class name. | | `processor` | no | Fully qualified Processor class name. | | `paginationEnabled` | no | Enables pagination for collection operations. | | `paginationItemsPerPage` | no | Default page size. | ### Operation types `Get`, `GetCollection`, `Post`, `Put`, `Patch`, `Delete`. ### Property types `string`, `integer`, `boolean`, `array`, `object`, `mixed`. Short aliases `int`, `bool`, `str`, and `arr` are accepted and normalized. ### Property attributes | Attribute | Description | |---|---| | `type` | One of the property types above. Required. | | `identifier` | Marks the property as the resource identifier. At least one identifier per resource is required. | | `required` | Required when creating the resource. | | `writable` | Whether the property can be written via the API (default: `true`). | | `readable` | Whether the property can be read via the API (default: `true`). | | `openapiContext` | Additional OpenAPI attributes (example, format, etc.). | For the full attribute list, see the [resource schemas reference](/docs/dg/dev/architecture/api-platform/resource-schemas.html). ## Troubleshooting ### Autocomplete or validation not active - **Verify the schema path.** Open the schema file from the IDE to confirm it exists and is valid JSON. - **Verify the file pattern.** PHPStorm and VSCode both require the YAML file's path to match the configured pattern. The default `**/resources/api/*/*.resource.yml` covers the standard Spryker layout (`src/{Org}/{Module}/resources/api/{api-type}/`). - **Restart the IDE.** PHPStorm: `File > Invalidate Caches / Restart`. VSCode: run `Developer: Reload Window` from the command palette. - **Check the extension** (VSCode only): ensure the Red Hat YAML extension is installed and enabled. ### False validation errors - **Property names** must match `^[a-zA-Z_][a-zA-Z0-9_]*$`. Hyphens and other special characters are rejected. - **Booleans** must be lowercase (`true` / `false`) in YAML. - **Types** must be one of the allowed values or aliases listed above. Custom strings are rejected. ### Schema changes not reflected - **PHPStorm:** `File > Invalidate Caches / Restart > Invalidate and Restart`. - **VSCode:** `Developer: Reload Window`. If the schema is referenced via a hosted URL, also disable any local HTTP cache or switch to the local file path while iterating. Tue, 19 May 2026 12:29:11 +0000 https://docs.spryker.com/docs/dg/dev/architecture/api-platform/ide-integration.html https://docs.spryker.com/docs/dg/dev/architecture/api-platform/ide-integration.html <p>This document describes how to create and enable API Platform resources in your Spryker project.</p> <h2 id="prerequisites">Prerequisites</h2> <p>Before creating API resources, ensure you have:</p> <ul> <li>Integrated API Platform as described in <a href="/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html">How to integrate API Platform</a></li> <li>Configured your application’s bundle files</li> <li>Configured API types as described in <a href="/docs/dg/dev/architecture/api-platform/configuration.html">API Platform Configuration</a></li> </ul> <h2 id="creating-your-first-api-resource">Creating your first API resource</h2> <h3 id="define-the-resource-schema">1. Define the resource schema</h3> <p>Create a schema file that defines your API resource structure. Schemas should be placed in <code>resources/api/{api-type}/</code> directory within your module.</p> <p><strong>Example: Customer resource for Back Office API</strong></p> <p><code>src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml</code></p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># yaml-language-server: $schema=../../../../../vendor/spryker/api-platform/resources/schemas/api-resource-schema-v1.json</span> <span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Customers</span> <span class="na">shortName</span><span class="pi">:</span> <span class="s">customers</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Customer</span><span class="nv"> </span><span class="s">resource</span><span class="nv"> </span><span class="s">for</span><span class="nv"> </span><span class="s">backend</span><span class="nv"> </span><span class="s">API"</span> <span class="na">provider</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Pyz</span><span class="se">\\</span><span class="s">Glue</span><span class="se">\\</span><span class="s">Customer</span><span class="se">\\</span><span class="s">Api</span><span class="se">\\</span><span class="s">Backend</span><span class="se">\\</span><span class="s">Provider</span><span class="se">\\</span><span class="s">CustomerBackendProvider"</span> <span class="na">processor</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Pyz</span><span class="se">\\</span><span class="s">Glue</span><span class="se">\\</span><span class="s">Customer</span><span class="se">\\</span><span class="s">Api</span><span class="se">\\</span><span class="s">Backend</span><span class="se">\\</span><span class="s">Processor</span><span class="se">\\</span><span class="s">CustomerBackendProcessor"</span> <span class="na">paginationEnabled</span><span class="pi">:</span> <span class="no">true</span> <span class="na">paginationItemsPerPage</span><span class="pi">:</span> <span class="m">10</span> <span class="na">operations</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Post</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Get</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">GetCollection</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Patch</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Delete</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">idCustomer</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">integer</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">The</span><span class="nv"> </span><span class="s">unique</span><span class="nv"> </span><span class="s">identifier</span><span class="nv"> </span><span class="s">of</span><span class="nv"> </span><span class="s">the</span><span class="nv"> </span><span class="s">customer."</span> <span class="na">writable</span><span class="pi">:</span> <span class="no">false</span> <span class="na">email</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">The</span><span class="nv"> </span><span class="s">email</span><span class="nv"> </span><span class="s">address</span><span class="nv"> </span><span class="s">of</span><span class="nv"> </span><span class="s">a</span><span class="nv"> </span><span class="s">user</span><span class="nv"> </span><span class="s">or</span><span class="nv"> </span><span class="s">contact."</span> <span class="na">openapiContext</span><span class="pi">:</span> <span class="na">example</span><span class="pi">:</span> <span class="s2">"</span><span class="s">test@spryker.com"</span> <span class="na">firstName</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">The</span><span class="nv"> </span><span class="s">first</span><span class="nv"> </span><span class="s">name</span><span class="nv"> </span><span class="s">of</span><span class="nv"> </span><span class="s">a</span><span class="nv"> </span><span class="s">person."</span> <span class="na">openapiContext</span><span class="pi">:</span> <span class="na">example</span><span class="pi">:</span> <span class="s2">"</span><span class="s">John"</span> <span class="na">lastName</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">The</span><span class="nv"> </span><span class="s">last</span><span class="nv"> </span><span class="s">name</span><span class="nv"> </span><span class="s">of</span><span class="nv"> </span><span class="s">a</span><span class="nv"> </span><span class="s">user</span><span class="nv"> </span><span class="s">or</span><span class="nv"> </span><span class="s">customer."</span> <span class="na">openapiContext</span><span class="pi">:</span> <span class="na">example</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Doe"</span> <span class="na">customerReference</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">A</span><span class="nv"> </span><span class="s">unique</span><span class="nv"> </span><span class="s">reference</span><span class="nv"> </span><span class="s">for</span><span class="nv"> </span><span class="s">a</span><span class="nv"> </span><span class="s">customer."</span> <span class="na">writable</span><span class="pi">:</span> <span class="no">false</span> <span class="na">identifier</span><span class="pi">:</span> <span class="no">true</span> </code></pre></div></div> <h3 id="create-validation-schema">2. Create validation schema</h3> <p>Define validation rules in a separate validation schema file:</p> <p><code>src/Pyz/Glue/Customer/resources/api/backend/customers.validation.yml</code></p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">post</span><span class="pi">:</span> <span class="na">email</span><span class="pi">:</span> <span class="pi">-</span> <span class="s">NotBlank</span> <span class="pi">-</span> <span class="s">Email</span> <span class="na">firstName</span><span class="pi">:</span> <span class="pi">-</span> <span class="s">NotBlank</span> <span class="pi">-</span> <span class="na">Length</span><span class="pi">:</span> <span class="na">max</span><span class="pi">:</span> <span class="m">100</span> <span class="na">lastName</span><span class="pi">:</span> <span class="pi">-</span> <span class="s">NotBlank</span> <span class="pi">-</span> <span class="na">Length</span><span class="pi">:</span> <span class="na">max</span><span class="pi">:</span> <span class="m">100</span> <span class="na">patch</span><span class="pi">:</span> <span class="na">email</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">Optional</span><span class="pi">:</span> <span class="na">constraints</span><span class="pi">:</span> <span class="pi">-</span> <span class="s">NotBlank</span> <span class="pi">-</span> <span class="s">Email</span> <span class="na">firstName</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">Optional</span><span class="pi">:</span> <span class="na">constraints</span><span class="pi">:</span> <span class="pi">-</span> <span class="s">NotBlank</span> <span class="pi">-</span> <span class="na">Length</span><span class="pi">:</span> <span class="na">max</span><span class="pi">:</span> <span class="m">100</span> </code></pre></div></div> <h3 id="implement-the-provider">3. Implement the Provider</h3> <p>The Provider is responsible for fetching data (GET operations). Implement the <code>ProviderInterface</code>:</p> <p><code>src/Pyz/Glue/Customer/Api/Backend/Provider/CustomerBackendProvider.php</code></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Glue\Customer\Api\Backend\Provider</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ApiPlatform\Metadata\Operation</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ApiPlatform\State\Pagination\TraversablePaginator</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ApiPlatform\State\ProviderInterface</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Pyz\Glue\Customer\Business\CustomerFacadeInterface</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Api\Backend\CustomersBackendResource</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">CustomerBackendProvider</span> <span class="kd">implements</span> <span class="nc">ProviderInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">__construct</span><span class="p">(</span> <span class="k">private</span> <span class="kt">CustomerFacadeInterface</span> <span class="nv">$customerFacade</span><span class="p">,</span> <span class="p">)</span> <span class="p">{</span> <span class="p">}</span> <span class="cd">/** * @param \ApiPlatform\Metadata\Operation $operation * @param array&lt;string, mixed&gt; $uriVariables * @param array&lt;string, mixed&gt; $context * * @return object|array&lt;object&gt;|null */</span> <span class="k">public</span> <span class="k">function</span> <span class="n">provide</span><span class="p">(</span><span class="kt">Operation</span> <span class="nv">$operation</span><span class="p">,</span> <span class="kt">array</span> <span class="nv">$uriVariables</span> <span class="o">=</span> <span class="p">[],</span> <span class="kt">array</span> <span class="nv">$context</span> <span class="o">=</span> <span class="p">[]):</span> <span class="kt">object</span><span class="o">|</span><span class="k">array</span><span class="o">|</span><span class="kc">null</span> <span class="p">{</span> <span class="c1">// Single resource (GET /customers/{id})</span> <span class="k">if</span> <span class="p">(</span><span class="k">isset</span><span class="p">(</span><span class="nv">$uriVariables</span><span class="p">[</span><span class="s1">'customerReference'</span><span class="p">]))</span> <span class="p">{</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getCustomer</span><span class="p">(</span><span class="nv">$uriVariables</span><span class="p">[</span><span class="s1">'customerReference'</span><span class="p">]);</span> <span class="p">}</span> <span class="c1">// Collection (GET /customers)</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getCustomers</span><span class="p">(</span><span class="nv">$context</span><span class="p">);</span> <span class="p">}</span> <span class="k">private</span> <span class="k">function</span> <span class="n">getCustomer</span><span class="p">(</span><span class="kt">string</span> <span class="nv">$customerReference</span><span class="p">):</span> <span class="kt">?CustomersBackendResource</span> <span class="p">{</span> <span class="nv">$customerTransfer</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">customerFacade</span><span class="o">-&gt;</span><span class="nf">findCustomerByReference</span><span class="p">(</span><span class="nv">$customerReference</span><span class="p">);</span> <span class="k">if</span> <span class="p">(</span><span class="nv">$customerTransfer</span> <span class="o">===</span> <span class="kc">null</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="kc">null</span><span class="p">;</span> <span class="p">}</span> <span class="c1">// Map to API resource</span> <span class="nv">$resource</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">CustomersBackendResource</span><span class="p">();</span> <span class="nv">$resource</span><span class="o">-&gt;</span><span class="nf">fromArray</span><span class="p">(</span><span class="nv">$customerTransfer</span><span class="o">-&gt;</span><span class="nf">toArray</span><span class="p">());</span> <span class="k">return</span> <span class="nv">$resource</span><span class="p">;</span> <span class="p">}</span> <span class="k">private</span> <span class="k">function</span> <span class="n">getCustomers</span><span class="p">(</span><span class="kt">array</span> <span class="nv">$context</span><span class="p">):</span> <span class="kt">TraversablePaginator</span> <span class="p">{</span> <span class="nv">$filters</span> <span class="o">=</span> <span class="nv">$context</span><span class="p">[</span><span class="s1">'filters'</span><span class="p">]</span> <span class="o">??</span> <span class="p">[];</span> <span class="nv">$page</span> <span class="o">=</span> <span class="p">(</span><span class="n">int</span><span class="p">)</span> <span class="p">(</span><span class="nv">$filters</span><span class="p">[</span><span class="s1">'page'</span><span class="p">]</span> <span class="o">??</span> <span class="mi">1</span><span class="p">);</span> <span class="nv">$itemsPerPage</span> <span class="o">=</span> <span class="p">(</span><span class="n">int</span><span class="p">)</span> <span class="p">(</span><span class="nv">$filters</span><span class="p">[</span><span class="s1">'itemsPerPage'</span><span class="p">]</span> <span class="o">??</span> <span class="mi">10</span><span class="p">);</span> <span class="nv">$customerCollection</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">customerFacade</span><span class="o">-&gt;</span><span class="nf">getCustomerCollection</span><span class="p">(</span><span class="nv">$page</span><span class="p">,</span> <span class="nv">$itemsPerPage</span><span class="p">);</span> <span class="nv">$resources</span> <span class="o">=</span> <span class="p">[];</span> <span class="k">foreach</span> <span class="p">(</span><span class="nv">$customerCollection</span><span class="o">-&gt;</span><span class="nf">getCustomers</span><span class="p">()</span> <span class="k">as</span> <span class="nv">$customerTransfer</span><span class="p">)</span> <span class="p">{</span> <span class="nv">$resource</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">CustomersBackendResource</span><span class="p">();</span> <span class="nv">$resource</span><span class="o">-&gt;</span><span class="nf">fromArray</span><span class="p">(</span><span class="nv">$customerTransfer</span><span class="o">-&gt;</span><span class="nf">toArray</span><span class="p">());</span> <span class="nv">$resources</span><span class="p">[]</span> <span class="o">=</span> <span class="nv">$resource</span><span class="p">;</span> <span class="p">}</span> <span class="k">return</span> <span class="k">new</span> <span class="nc">TraversablePaginator</span><span class="p">(</span> <span class="k">new</span> <span class="err">\</span><span class="nf">ArrayObject</span><span class="p">(</span><span class="nv">$resources</span><span class="p">),</span> <span class="nv">$page</span><span class="p">,</span> <span class="nv">$itemsPerPage</span><span class="p">,</span> <span class="nv">$customerCollection</span><span class="o">-&gt;</span><span class="nf">getTotalCount</span><span class="p">()</span> <span class="p">);</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h3 id="implement-the-processor">4. Implement the Processor</h3> <p>The Processor handles data modifications (POST, PUT, PATCH, DELETE). Implement the <code>ProcessorInterface</code>:</p> <p><code>src/Pyz/Glue/Customer/Api/Backend/Processor/CustomerBackendProcessor.php</code></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Glue\Customer\Api\Backend\Processor</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ApiPlatform\Metadata\Delete</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ApiPlatform\Metadata\Operation</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ApiPlatform\Metadata\Patch</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ApiPlatform\Metadata\Post</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ApiPlatform\State\ProcessorInterface</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Pyz\Glue\Customer\Business\CustomerFacadeInterface</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Generated\Api\Backend\CustomersBackendResource</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">CustomerBackendProcessor</span> <span class="kd">implements</span> <span class="nc">ProcessorInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">__construct</span><span class="p">(</span> <span class="k">private</span> <span class="kt">CustomerFacadeInterface</span> <span class="nv">$customerFacade</span><span class="p">,</span> <span class="p">)</span> <span class="p">{</span> <span class="p">}</span> <span class="cd">/** * @param mixed $data * @param \ApiPlatform\Metadata\Operation $operation * @param array&lt;string, mixed&gt; $uriVariables * @param array&lt;string, mixed&gt; $context * * @return mixed */</span> <span class="k">public</span> <span class="k">function</span> <span class="n">process</span><span class="p">(</span><span class="kt">mixed</span> <span class="nv">$data</span><span class="p">,</span> <span class="kt">Operation</span> <span class="nv">$operation</span><span class="p">,</span> <span class="kt">array</span> <span class="nv">$uriVariables</span> <span class="o">=</span> <span class="p">[],</span> <span class="kt">array</span> <span class="nv">$context</span> <span class="o">=</span> <span class="p">[]):</span> <span class="kt">mixed</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="nv">$operation</span> <span class="k">instanceof</span> <span class="nc">Delete</span><span class="p">)</span> <span class="p">{</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">customerFacade</span><span class="o">-&gt;</span><span class="nf">deleteCustomer</span><span class="p">(</span><span class="nv">$uriVariables</span><span class="p">[</span><span class="s1">'customerReference'</span><span class="p">]);</span> <span class="k">return</span> <span class="kc">null</span><span class="p">;</span> <span class="p">}</span> <span class="k">if</span> <span class="p">(</span><span class="nv">$operation</span> <span class="k">instanceof</span> <span class="nc">Post</span><span class="p">)</span> <span class="p">{</span> <span class="nv">$customerTransfer</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">mapToTransfer</span><span class="p">(</span><span class="nv">$data</span><span class="p">);</span> <span class="nv">$savedCustomer</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">customerFacade</span><span class="o">-&gt;</span><span class="nf">createCustomer</span><span class="p">(</span><span class="nv">$customerTransfer</span><span class="p">);</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">mapToResource</span><span class="p">(</span><span class="nv">$savedCustomer</span><span class="p">);</span> <span class="p">}</span> <span class="k">if</span> <span class="p">(</span><span class="nv">$operation</span> <span class="k">instanceof</span> <span class="nc">Patch</span><span class="p">)</span> <span class="p">{</span> <span class="nv">$customerTransfer</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">mapToTransfer</span><span class="p">(</span><span class="nv">$data</span><span class="p">);</span> <span class="nv">$customerTransfer</span><span class="o">-&gt;</span><span class="nf">setCustomerReference</span><span class="p">(</span><span class="nv">$uriVariables</span><span class="p">[</span><span class="s1">'customerReference'</span><span class="p">]);</span> <span class="nv">$updatedCustomer</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">customerFacade</span><span class="o">-&gt;</span><span class="nf">updateCustomer</span><span class="p">(</span><span class="nv">$customerTransfer</span><span class="p">);</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">mapToResource</span><span class="p">(</span><span class="nv">$updatedCustomer</span><span class="p">);</span> <span class="p">}</span> <span class="k">return</span> <span class="kc">null</span><span class="p">;</span> <span class="p">}</span> <span class="k">private</span> <span class="k">function</span> <span class="n">mapToTransfer</span><span class="p">(</span><span class="kt">CustomersBackendResource</span> <span class="nv">$resource</span><span class="p">):</span> <span class="kt">CustomerTransfer</span> <span class="p">{</span> <span class="nv">$transfer</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">CustomerTransfer</span><span class="p">();</span> <span class="nv">$transfer</span><span class="o">-&gt;</span><span class="nf">fromArray</span><span class="p">(</span><span class="nv">$resource</span><span class="o">-&gt;</span><span class="nf">toArray</span><span class="p">(),</span> <span class="kc">true</span><span class="p">);</span> <span class="k">return</span> <span class="nv">$transfer</span><span class="p">;</span> <span class="p">}</span> <span class="k">private</span> <span class="k">function</span> <span class="n">mapToResource</span><span class="p">(</span><span class="kt">CustomerTransfer</span> <span class="nv">$transfer</span><span class="p">):</span> <span class="kt">CustomersBackendResource</span> <span class="p">{</span> <span class="nv">$resource</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">CustomersBackendResource</span><span class="p">();</span> <span class="nv">$resource</span><span class="o">-&gt;</span><span class="nf">fromArray</span><span class="p">(</span><span class="nv">$transfer</span><span class="o">-&gt;</span><span class="nf">toArray</span><span class="p">());</span> <span class="k">return</span> <span class="nv">$resource</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h3 id="generate-the-resource">5. Generate the resource</h3> <p>Run the generation command to create the API resource class:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>docker/sdk cli <span class="nv">GLUE_APPLICATION</span><span class="o">=</span>GLUE_BACKEND glue api:generate backend </code></pre></div></div> <p>This generates:</p> <p><code>src/Generated/Api/Backend/CustomersBackendResource.php</code></p> <p>The generated class includes:</p> <ul> <li>API Platform attributes (<code>#[ApiResource]</code>, <code>#[ApiProperty]</code>)</li> <li>Validation constraints (<code>#[Assert\NotBlank]</code>, <code>#[Assert\Email]</code>, etc.)</li> <li>Public properties for all defined fields</li> <li>Getters and setters</li> <li><code>toArray()</code> and <code>fromArray()</code> methods</li> </ul> <h3 id="register-services-in-the-dependency-injection-container">6. Register services in the Dependency Injection container</h3> <p>Make your Provider and Processor available through dependency injection: <strong>config/Glue/ApplicationServices.php</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">use</span> <span class="nc">Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator</span><span class="p">;</span> <span class="k">return</span> <span class="k">static</span> <span class="k">function</span> <span class="p">(</span><span class="kt">ContainerConfigurator</span> <span class="nv">$configurator</span><span class="p">):</span> <span class="kt">void</span> <span class="p">{</span> <span class="nv">$services</span> <span class="o">=</span> <span class="nv">$configurator</span><span class="o">-&gt;</span><span class="nf">services</span><span class="p">()</span> <span class="o">-&gt;</span><span class="nf">defaults</span><span class="p">()</span> <span class="o">-&gt;</span><span class="nf">autowire</span><span class="p">()</span> <span class="o">-&gt;</span><span class="k">public</span><span class="p">()</span> <span class="o">-&gt;</span><span class="nf">autoconfigure</span><span class="p">();</span> <span class="c1">// Auto-discover services from your project modules</span> <span class="nv">$services</span><span class="o">-&gt;</span><span class="nf">load</span><span class="p">(</span><span class="s1">'Pyz\\Glue\\'</span><span class="p">,</span> <span class="s1">'../../../src/Pyz/Glue/'</span><span class="p">);</span> <span class="p">};</span> </code></pre></div></div> <h3 id="test-your-api">7. Test your API</h3> <p>After generation, your API is immediately available:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># List all customers</span> GET /customers <span class="c"># Get single customer</span> GET /customers/<span class="o">{</span>customerReference<span class="o">}</span> <span class="c"># Create customer</span> POST /customers <span class="o">{</span> <span class="s2">"email"</span>: <span class="s2">"john@example.com"</span>, <span class="s2">"firstName"</span>: <span class="s2">"John"</span>, <span class="s2">"lastName"</span>: <span class="s2">"Doe"</span> <span class="o">}</span> <span class="c"># Update customer</span> PATCH /customers/<span class="o">{</span>customerReference<span class="o">}</span> <span class="o">{</span> <span class="s2">"firstName"</span>: <span class="s2">"Jane"</span> <span class="o">}</span> <span class="c"># Delete customer</span> DELETE /customers/<span class="o">{</span>customerReference<span class="o">}</span> </code></pre></div></div> <h2 id="creating-codebucket-specific-resources">Creating CodeBucket-specific resources</h2> <p>CodeBucket support enables you to create Code Bucket-specific API resource variants that are resolved at runtime based on the <code>APPLICATION_CODE_BUCKET</code> environment constant.</p> <h3 id="when-to-use-codebucket-resources">When to use CodeBucket resources</h3> <p>Create CodeBucket variants when you need:</p> <ul> <li>Code Bucket-specific properties (EU GDPR fields, tax rates, compliance data)</li> <li>Code Bucket-specific validation rules (country-specific requirements)</li> <li>Country-specific business logic</li> <li>Feature variations per Code Bucket</li> </ul> <h3 id="quick-example">Quick example</h3> <p><strong>Base resource:</strong></p> <p><code>src/Pyz/Glue/Customer/resources/api/backend/customers.resource.yml</code></p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Customers</span> <span class="na">shortName</span><span class="pi">:</span> <span class="s">customers</span> <span class="na">operations</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Get</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Post</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">customerReference</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">identifier</span><span class="pi">:</span> <span class="no">true</span> <span class="na">email</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">firstName</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> </code></pre></div></div> <p><strong>EU-specific variant:</strong></p> <p><code>src/Pyz/Glue/CustomerEU/resources/api/backend/customers.resource.yml</code></p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Customers</span> <span class="na">shortName</span><span class="pi">:</span> <span class="s">customers</span> <span class="na">codeBucket</span><span class="pi">:</span> <span class="s">EU</span> <span class="na">operations</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Get</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Post</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">customerReference</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">identifier</span><span class="pi">:</span> <span class="no">true</span> <span class="na">email</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">firstName</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="c1"># EU-specific properties</span> <span class="na">gdprConsentDate</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Date</span><span class="nv"> </span><span class="s">of</span><span class="nv"> </span><span class="s">GDPR</span><span class="nv"> </span><span class="s">consent"</span> <span class="na">dataPrivacyOfficerEmail</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Data</span><span class="nv"> </span><span class="s">privacy</span><span class="nv"> </span><span class="s">officer</span><span class="nv"> </span><span class="s">contact"</span> </code></pre></div></div> <p><strong>Generate resources:</strong></p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>docker/sdk cli <span class="nv">GLUE_APPLICATION</span><span class="o">=</span>GLUE_BACKEND glue api:generate backend </code></pre></div></div> <p>This generates:</p> <ul> <li><code>CustomersBackendResource.php</code> (base)</li> <li><code>CustomersEUBackendResource.php</code> (with <code>CODE_BUCKET = 'EU'</code>)</li> </ul> <p><strong>Runtime behavior:</strong></p> <ul> <li>Request to <code>glue.eu.spryker.local/customers</code> → Uses <code>CustomersEUBackendResource</code></li> <li>Request to <code>glue.de.spryker.local/customers</code> → Uses <code>CustomersBackendResource</code> (fallback)</li> <li>Request to <code>glue.at.spryker.local/customers</code> → Uses <code>CustomersBackendResource</code> (or <code>CustomersATBackendResource</code> if variant exists)</li> </ul> <p>For a comprehensive guide including Provider implementation and advanced scenarios, see <a href="/docs/dg/dev/architecture/api-platform/code-buckets.html">CodeBucket Support</a>.</p> <h2 id="api-types-and-use-cases">API types and use cases</h2> <p>Spryker supports multiple API types for different use cases:</p> <h3 id="storefront-api-glue">Storefront API (Glue)</h3> <ul> <li><strong>API Type:</strong> <code>storefront</code></li> <li><strong>Module location:</strong> <code>src/Spryker/{Module}/resources/api/storefront/</code></li> <li><strong>Generated namespace:</strong> <code>Generated\Api\Storefront</code></li> <li><strong>Use cases:</strong> Customer-facing APIs, mobile apps, PWAs</li> </ul> <h3 id="back-office-api-glue">Back Office API (Glue)</h3> <ul> <li><strong>API Type:</strong> <code>backend</code></li> <li><strong>Module location:</strong> <code>src/Pyz/Glue/{Module}/resources/api/backend/</code></li> <li><strong>Generated namespace:</strong> <code>Generated\Api\Backend</code></li> <li><strong>Use cases:</strong> Admin panels, internal tools, ERP integrations</li> </ul> <h3 id="merchant-portal-api">Merchant Portal API</h3> <ul> <li><strong>API Type:</strong> <code>merchant-portal</code></li> <li><strong>Module location:</strong> <code>src/Spryker/{Module}/resources/api/merchant-portal/</code></li> <li><strong>Generated namespace:</strong> <code>Generated\Api\MerchantPortal</code></li> <li><strong>Use cases:</strong> Marketplace merchant interfaces</li> </ul> <h2 id="schema-layering-and-inheritance">Schema layering and inheritance</h2> <p>API Platform supports multi-layer schema definitions with automatic merging:</p> <h3 id="core-layer">Core layer</h3> <p><code>vendor/spryker/customer/resources/api/backend/customer.resource.yml</code> - Base definition</p> <h3 id="feature-layer">Feature layer</h3> <p><code>src/SprykerFeature/CustomerRelationManagement/resources/api/backend/customer.resource.yml</code> - Feature enhancements</p> <h3 id="project-layer">Project layer</h3> <p><code>src/Pyz/Glue/Customer/resources/api/backend/customer.resource.yml</code> - Project customizations</p> <p>The generator automatically merges these schemas with project layer taking precedence.</p> <h2 id="debugging-resources">Debugging resources</h2> <p>Use the debug command to inspect resources:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># List all resources</span> docker/sdk cli glue api:debug <span class="nt">--list</span> <span class="c"># Show resource details</span> docker/sdk cli glue api:debug customers <span class="nt">--api-type</span><span class="o">=</span>backend <span class="c"># Show merged schema</span> docker/sdk cli glue api:debug customers <span class="nt">--api-type</span><span class="o">=</span>backend <span class="nt">--show-merged</span> <span class="c"># Show source files</span> docker/sdk cli glue api:debug customers <span class="nt">--api-type</span><span class="o">=</span>backend <span class="nt">--show-sources</span> </code></pre></div></div> <h2 id="next-steps">Next steps</h2> <ul> <li><a href="/docs/dg/dev/architecture/api-platform/resource-schemas.html">Resource Schemas</a> - Deep dive into resource schema syntax</li> <li><a href="/docs/dg/dev/architecture/api-platform/validation-schemas.html">Validation Schemas</a> - Define validation rules for your resources</li> <li><a href="/docs/dg/dev/architecture/api-platform/code-buckets.html">CodeBucket Support</a> - Create Code Bucket-specific resources</li> <li><a href="/docs/dg/dev/architecture/api-platform/testing.html">API Platform Testing</a> - Learn how to write tests for your API resources</li> <li><a href="/docs/dg/dev/architecture/api-platform/troubleshooting.html">Troubleshooting</a> - Common issues and solutions</li> </ul> Tue, 19 May 2026 12:29:11 +0000 https://docs.spryker.com/docs/dg/dev/architecture/api-platform/enablement.html https://docs.spryker.com/docs/dg/dev/architecture/api-platform/enablement.html <p>This document explains how to create and use CodeBucket-specific API resources in API Platform.</p> <h2 id="overview">Overview</h2> <p>CodeBucket support enables API Platform to serve different resource variants based on the runtime <code>APPLICATION_CODE_BUCKET</code> environment constant. This allows you to maintain Code Bucket-specific API resources without requiring separate container compilations for each Code Bucket.</p> <h3 id="use-cases">Use cases</h3> <p>Use CodeBucket resources when you need:</p> <ul> <li><strong>Code Bucket-specific properties</strong>: EU-specific GDPR fields, tax rates, compliance data</li> <li><strong>Code Bucket-specific validation</strong>: Different validation rules per Code Bucket or country</li> <li><strong>Localized business logic</strong>: Country-specific processing requirements</li> </ul> <h3 id="key-benefits">Key benefits</h3> <ul> <li><strong>Single container</strong>: Compile once, serve hundreds of CodeBuckets</li> <li><strong>Runtime resolution</strong>: Automatic selection of correct resource variant</li> <li><strong>Graceful fallback</strong>: Base resources used when CodeBucket variant doesn’t exist</li> <li><strong>No duplication</strong>: Share common logic while extending for specific needs</li> </ul> <h2 id="how-codebucket-resolution-works">How CodeBucket resolution works</h2> <h3 id="architecture-overview">Architecture overview</h3> <p>API Platform uses a decorator pattern to intercept resource resolution and select the appropriate CodeBucket variant at runtime:</p> <pre><code class="language-MARKDOWN">>Request → Symfony Routing → API Platform ↓ CodeBucket Decorators ↓ ┌──────────────────┴──────────────────┐ │ │ Resource Class Resolver Resource Name Collection Factory (Runtime resolution) (Compile-time filtering) │ │ └──────────────────┬──────────────────┘ ↓ Selected Resource Variant (Base or CodeBucket-specific) </code></pre> <h3 id="runtime-resolution-flow">Runtime resolution flow</h3> <pre><code class="language-MARKDOWN">>1. Request: GET glue-backend.eu.spryker.local/stores APPLICATION_CODE_BUCKET = 'EU' 2. CodeBucketResourceNameCollectionFactory → Filters resource collection at compile time → Includes only EU variants or base resources (no conflicts) 3. CodeBucketResourceClassResolver → Reads APPLICATION_CODE_BUCKET = 'EU' → Base class: StoresBackendResource → Builds variant name: StoresEUBackendResource → Checks: class_exists('Generated\Api\Backend\StoresEUBackendResource') → Validates: StoresEUBackendResource::CODE_BUCKET === 'EU' → Returns: StoresEUBackendResource 4. API Platform executes with EU-specific resource → Properties: base + EU-specific fields → Validations: base + EU-specific rules </code></pre> <h3 id="codebucket-detection-mechanism">CodeBucket detection mechanism</h3> <p>The system identifies CodeBucket resources using three checks:</p> <ol> <li><strong>Class existence</strong>: <code>class_exists($codeBucketClassName)</code></li> <li><strong>Constant check</strong>: <code>defined(&quot;$className::CODE_BUCKET&quot;)</code></li> <li><strong>Value match</strong>: <code>constant(&quot;$className::CODE_BUCKET&quot;) === $currentCodeBucket</code></li> </ol> <h3 id="generated-codebucket-constant">Generated CODE_BUCKET constant</h3> <p>CodeBucket resources automatically get a <code>CODE_BUCKET</code> constant during generation:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// StoresEUBackendResource.php (EU variant)</span> <span class="k">final</span> <span class="kd">class</span> <span class="nc">StoresEUBackendResource</span> <span class="p">{</span> <span class="k">public</span> <span class="k">const</span> <span class="no">string</span> <span class="no">CODE_BUCKET</span> <span class="o">=</span> <span class="s1">'EU'</span><span class="p">;</span> <span class="c1">// Properties...</span> <span class="p">}</span> <span class="c1">// StoresBackendResource.php (base - no constant)</span> <span class="k">final</span> <span class="kd">class</span> <span class="nc">StoresBackendResource</span> <span class="p">{</span> <span class="c1">// Properties... (no CODE_BUCKET constant)</span> <span class="p">}</span> </code></pre></div></div> <h2 id="resource-naming-conventions">Resource naming conventions</h2> <h3 id="file-naming-pattern">File naming pattern</h3> <p>Resource schemas follow the pattern: <code>{resource-name}.resource.yml</code> Validation schemas follow the pattern: <code>{resource-name}.validation.yml</code></p> <p>Each YAML file contains exactly one resource definition. To create a CodeBucket variant, place its schema in a <strong>separate module directory</strong> named after the variant (for example, <code>StoresApiEU</code>, <code>StoresApiAT</code>) and set the <code>codeBucket:</code> property inside the file. The filename stays the same across all variants — only the parent module directory and the <code>codeBucket:</code> value differ.</p> <pre><code class="language-MARKDOWN">>src/Pyz/Glue/StoresApi/resources/api/backend/ # Base variant module ├── stores.resource.yml # No codeBucket property └── stores.validation.yml src/Pyz/Glue/StoresApiEU/resources/api/backend/ # EU variant module ├── stores.resource.yml # codeBucket: EU └── stores.validation.yml # codeBucket: EU src/Pyz/Glue/StoresApiAT/resources/api/backend/ # AT variant module ├── stores.resource.yml # codeBucket: AT └── stores.validation.yml # codeBucket: AT </code></pre> <h3 id="generated-class-naming-pattern">Generated class naming pattern</h3> <p>The generator creates classes following: <code>{ResourceName}{CodeBucket}{ApiType}Resource</code></p> <table> <thead> <tr> <th>Schema File</th> <th>CodeBucket (defined in file)</th> <th>Generated Class</th> </tr> </thead> <tbody> <tr> <td><code>stores.resource.yml</code></td> <td>None (base)</td> <td><code>StoresBackendResource</code></td> </tr> <tr> <td><code>stores.resource.yml</code></td> <td>EU</td> <td><code>StoresEUBackendResource</code></td> </tr> <tr> <td><code>stores.resource.yml</code></td> <td>AT</td> <td><code>StoresATBackendResource</code></td> </tr> <tr> <td><code>stores.resource.yml</code> (Storefront)</td> <td>EU</td> <td><code>StoresEUStorefrontResource</code></td> </tr> </tbody> </table> <h3 id="url-consistency">URL consistency</h3> <p>All CodeBucket variants share the same URL path, with the Code Bucket defined in the domain:</p> <ul> <li>EU: <code>glue-backend.eu.spryker.local/stores</code> → <code>StoresEUBackendResource</code></li> <li>AT: <code>glue-backend.at.spryker.local/stores</code> → <code>StoresATBackendResource</code></li> <li>DE: <code>glue-backend.de.spryker.local/stores</code> → <code>StoresBackendResource</code> (or <code>StoresDEBackendResource</code> if variant exists)</li> </ul> <p>The URL path is identical (<code>/stores</code>), but the Code Bucket in the domain determines which resource variant is used. Only the properties, validations, and business logic differ between variants.</p> <h2 id="creating-codebucket-resources">Creating CodeBucket resources</h2> <h3 id="basic-example">Basic example</h3> <p><strong>Step 1: Create base resource</strong></p> <p><code>src/Pyz/Glue/StoresApi/resources/api/backend/stores.resource.yml</code></p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Stores</span> <span class="na">shortName</span><span class="pi">:</span> <span class="s">stores</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Store</span><span class="nv"> </span><span class="s">resource"</span> <span class="na">provider</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Pyz</span><span class="se">\\</span><span class="s">Glue</span><span class="se">\\</span><span class="s">StoresApi</span><span class="se">\\</span><span class="s">Api</span><span class="se">\\</span><span class="s">Backend</span><span class="se">\\</span><span class="s">Provider</span><span class="se">\\</span><span class="s">StoreBackendProvider"</span> <span class="na">processor</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Pyz</span><span class="se">\\</span><span class="s">Glue</span><span class="se">\\</span><span class="s">StoresApi</span><span class="se">\\</span><span class="s">Api</span><span class="se">\\</span><span class="s">Backend</span><span class="se">\\</span><span class="s">Processor</span><span class="se">\\</span><span class="s">StoreBackendProcessor"</span> <span class="na">operations</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Get</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">GetCollection</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">idStore</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">integer</span> <span class="na">writable</span><span class="pi">:</span> <span class="no">false</span> <span class="na">identifier</span><span class="pi">:</span> <span class="no">true</span> <span class="na">name</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Store</span><span class="nv"> </span><span class="s">name"</span> <span class="na">timezone</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Store</span><span class="nv"> </span><span class="s">timezone"</span> </code></pre></div></div> <p><strong>Step 2: Define the CodeBucket variant in a separate module</strong></p> <p>Create a new module directory whose name carries the CodeBucket suffix (<code>StoresApiEU</code>) and place the variant’s schema there. The filename stays <code>stores.resource.yml</code>; the <code>codeBucket:</code> property inside the file declares which variant it belongs to.</p> <p><code>src/Pyz/Glue/StoresApiEU/resources/api/backend/stores.resource.yml</code></p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Stores</span> <span class="na">shortName</span><span class="pi">:</span> <span class="s">stores</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">EU-specific</span><span class="nv"> </span><span class="s">store</span><span class="nv"> </span><span class="s">resource"</span> <span class="na">codeBucket</span><span class="pi">:</span> <span class="s">EU</span> <span class="c1"># Same provider and processor as the base resource</span> <span class="na">provider</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Pyz</span><span class="se">\\</span><span class="s">Glue</span><span class="se">\\</span><span class="s">StoresApi</span><span class="se">\\</span><span class="s">Api</span><span class="se">\\</span><span class="s">Backend</span><span class="se">\\</span><span class="s">Provider</span><span class="se">\\</span><span class="s">StoreBackendProvider"</span> <span class="na">processor</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Pyz</span><span class="se">\\</span><span class="s">Glue</span><span class="se">\\</span><span class="s">StoresApi</span><span class="se">\\</span><span class="s">Api</span><span class="se">\\</span><span class="s">Backend</span><span class="se">\\</span><span class="s">Processor</span><span class="se">\\</span><span class="s">StoreBackendProcessor"</span> <span class="na">operations</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Get</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">GetCollection</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">idStore</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">integer</span> <span class="na">writable</span><span class="pi">:</span> <span class="no">false</span> <span class="na">identifier</span><span class="pi">:</span> <span class="no">true</span> <span class="na">name</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Store</span><span class="nv"> </span><span class="s">name"</span> <span class="na">timezone</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Store</span><span class="nv"> </span><span class="s">timezone"</span> <span class="c1"># EU-specific properties</span> <span class="na">taxRate</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">number</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">EU</span><span class="nv"> </span><span class="s">tax</span><span class="nv"> </span><span class="s">rate"</span> <span class="na">openapiContext</span><span class="pi">:</span> <span class="na">example</span><span class="pi">:</span> <span class="m">19.0</span> <span class="na">gdprContactEmail</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">GDPR</span><span class="nv"> </span><span class="s">contact</span><span class="nv"> </span><span class="s">email"</span> <span class="na">openapiContext</span><span class="pi">:</span> <span class="na">example</span><span class="pi">:</span> <span class="s2">"</span><span class="s">privacy@example.com"</span> <span class="na">vatRegistrationNumber</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">VAT</span><span class="nv"> </span><span class="s">registration</span><span class="nv"> </span><span class="s">number"</span> </code></pre></div></div> <section class='info-block '><i class='info-block__icon icon-info'></i><div class='info-block__content'><div class="info-block__title">One resource per file</div> <p>Each schema file must contain exactly one top-level <code>resource:</code> block. CodeBucket variants live in their own files in their own module directories — they cannot be stacked inside a single YAML document.</p> </div></section> <p><strong>Step 3: Create the variant’s validation schema</strong></p> <p>Place the matching validation file alongside the variant resource, in the same module directory. Set <code>codeBucket:</code> at the root so the parser pairs it with the EU resource variant.</p> <p><code>src/Pyz/Glue/StoresApiEU/resources/api/backend/stores.validation.yml</code></p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">codeBucket</span><span class="pi">:</span> <span class="s">EU</span> <span class="na">post</span><span class="pi">:</span> <span class="na">taxRate</span><span class="pi">:</span> <span class="pi">-</span> <span class="s">NotBlank</span> <span class="pi">-</span> <span class="na">Range</span><span class="pi">:</span> <span class="na">min</span><span class="pi">:</span> <span class="m">0</span> <span class="na">max</span><span class="pi">:</span> <span class="m">100</span> <span class="na">gdprContactEmail</span><span class="pi">:</span> <span class="pi">-</span> <span class="s">NotBlank</span> <span class="pi">-</span> <span class="s">Email</span> <span class="na">vatRegistrationNumber</span><span class="pi">:</span> <span class="pi">-</span> <span class="s">NotBlank</span> <span class="pi">-</span> <span class="na">Regex</span><span class="pi">:</span> <span class="na">pattern</span><span class="pi">:</span> <span class="s1">'</span><span class="s">/^[A-Z]{2}[0-9]{8,12}$/'</span> <span class="na">message</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Invalid</span><span class="nv"> </span><span class="s">VAT</span><span class="nv"> </span><span class="s">format"</span> </code></pre></div></div> <p><strong>Step 4: Generate resources</strong></p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>docker/sdk cli <span class="nv">GLUE_APPLICATION</span><span class="o">=</span>GLUE_BACKEND glue api:generate backend </code></pre></div></div> <p>This generates:</p> <ul> <li><code>src/Generated/Api/Backend/StoresBackendResource.php</code> (base)</li> <li><code>src/Generated/Api/Backend/StoresEUBackendResource.php</code> (with <code>CODE_BUCKET = 'EU'</code>)</li> </ul> <p><strong>Step 5: Implement Provider with CodeBucket awareness</strong></p> <p><code>src/Pyz/Glue/StoresApi/Api/Backend/Provider/StoreBackendProvider.php</code></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Pyz\Glue\StoresApi\Api\Backend\Provider</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ApiPlatform\Metadata\Operation</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ApiPlatform\State\ProviderInterface</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Pyz\Glue\StoresApi\Business\StoreFacadeInterface</span><span class="p">;</span> <span class="kd">class</span> <span class="nc">StoreBackendProvider</span> <span class="kd">implements</span> <span class="nc">ProviderInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">__construct</span><span class="p">(</span> <span class="k">protected</span> <span class="kt">StoreFacadeInterface</span> <span class="nv">$storeFacade</span><span class="p">,</span> <span class="p">)</span> <span class="p">{</span> <span class="p">}</span> <span class="k">public</span> <span class="k">function</span> <span class="n">provide</span><span class="p">(</span><span class="kt">Operation</span> <span class="nv">$operation</span><span class="p">,</span> <span class="kt">array</span> <span class="nv">$uriVariables</span> <span class="o">=</span> <span class="p">[],</span> <span class="kt">array</span> <span class="nv">$context</span> <span class="o">=</span> <span class="p">[]):</span> <span class="kt">object</span><span class="o">|</span><span class="k">array</span><span class="o">|</span><span class="kc">null</span> <span class="p">{</span> <span class="k">if</span> <span class="p">(</span><span class="k">isset</span><span class="p">(</span><span class="nv">$uriVariables</span><span class="p">[</span><span class="s1">'idStore'</span><span class="p">]))</span> <span class="p">{</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getStore</span><span class="p">((</span><span class="n">int</span><span class="p">)</span> <span class="nv">$uriVariables</span><span class="p">[</span><span class="s1">'idStore'</span><span class="p">],</span> <span class="nv">$operation</span><span class="p">);</span> <span class="p">}</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">getStores</span><span class="p">(</span><span class="nv">$operation</span><span class="p">);</span> <span class="p">}</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getStore</span><span class="p">(</span><span class="kt">int</span> <span class="nv">$idStore</span><span class="p">,</span> <span class="kt">Operation</span> <span class="nv">$operation</span><span class="p">):</span> <span class="kt">?object</span> <span class="p">{</span> <span class="nv">$storeTransfer</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">storeFacade</span><span class="o">-&gt;</span><span class="nf">findStoreById</span><span class="p">(</span><span class="nv">$idStore</span><span class="p">);</span> <span class="k">if</span> <span class="p">(</span><span class="nv">$storeTransfer</span> <span class="o">===</span> <span class="kc">null</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="kc">null</span><span class="p">;</span> <span class="p">}</span> <span class="nv">$resourceClass</span> <span class="o">=</span> <span class="nv">$operation</span><span class="o">-&gt;</span><span class="nf">getClass</span><span class="p">();</span> <span class="nv">$resource</span> <span class="o">=</span> <span class="k">new</span> <span class="nv">$resourceClass</span><span class="p">();</span> <span class="nv">$resource</span><span class="o">-&gt;</span><span class="nf">fromArray</span><span class="p">(</span><span class="nv">$storeTransfer</span><span class="o">-&gt;</span><span class="nf">toArray</span><span class="p">());</span> <span class="c1">// Add EU-specific data if this is an EU resource</span> <span class="k">if</span> <span class="p">(</span><span class="nb">defined</span><span class="p">(</span><span class="s2">"</span><span class="nv">$resourceClass</span><span class="s2">::CODE_BUCKET"</span><span class="p">)</span> <span class="o">&amp;&amp;</span> <span class="nv">$resourceClass</span><span class="o">::</span><span class="no">CODE_BUCKET</span> <span class="o">===</span> <span class="s1">'EU'</span><span class="p">)</span> <span class="p">{</span> <span class="nv">$resource</span><span class="o">-&gt;</span><span class="n">taxRate</span> <span class="o">=</span> <span class="nv">$storeTransfer</span><span class="o">-&gt;</span><span class="nf">getTaxRate</span><span class="p">();</span> <span class="nv">$resource</span><span class="o">-&gt;</span><span class="n">gdprContactEmail</span> <span class="o">=</span> <span class="nv">$storeTransfer</span><span class="o">-&gt;</span><span class="nf">getGdprContactEmail</span><span class="p">();</span> <span class="nv">$resource</span><span class="o">-&gt;</span><span class="n">vatRegistrationNumber</span> <span class="o">=</span> <span class="nv">$storeTransfer</span><span class="o">-&gt;</span><span class="nf">getVatRegistrationNumber</span><span class="p">();</span> <span class="p">}</span> <span class="k">return</span> <span class="nv">$resource</span><span class="p">;</span> <span class="p">}</span> <span class="k">protected</span> <span class="k">function</span> <span class="n">getStores</span><span class="p">(</span><span class="kt">Operation</span> <span class="nv">$operation</span><span class="p">):</span> <span class="kt">array</span> <span class="p">{</span> <span class="nv">$stores</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">storeFacade</span><span class="o">-&gt;</span><span class="nf">getAllStores</span><span class="p">();</span> <span class="nv">$resources</span> <span class="o">=</span> <span class="p">[];</span> <span class="k">foreach</span> <span class="p">(</span><span class="nv">$stores</span> <span class="k">as</span> <span class="nv">$storeTransfer</span><span class="p">)</span> <span class="p">{</span> <span class="nv">$resourceClass</span> <span class="o">=</span> <span class="nv">$operation</span><span class="o">-&gt;</span><span class="nf">getClass</span><span class="p">();</span> <span class="nv">$resource</span> <span class="o">=</span> <span class="k">new</span> <span class="nv">$resourceClass</span><span class="p">();</span> <span class="nv">$resource</span><span class="o">-&gt;</span><span class="nf">fromArray</span><span class="p">(</span><span class="nv">$storeTransfer</span><span class="o">-&gt;</span><span class="nf">toArray</span><span class="p">());</span> <span class="k">if</span> <span class="p">(</span><span class="nb">defined</span><span class="p">(</span><span class="s2">"</span><span class="nv">$resourceClass</span><span class="s2">::CODE_BUCKET"</span><span class="p">)</span> <span class="o">&amp;&amp;</span> <span class="nv">$resourceClass</span><span class="o">::</span><span class="no">CODE_BUCKET</span> <span class="o">===</span> <span class="s1">'EU'</span><span class="p">)</span> <span class="p">{</span> <span class="nv">$resource</span><span class="o">-&gt;</span><span class="n">taxRate</span> <span class="o">=</span> <span class="nv">$storeTransfer</span><span class="o">-&gt;</span><span class="nf">getTaxRate</span><span class="p">();</span> <span class="nv">$resource</span><span class="o">-&gt;</span><span class="n">gdprContactEmail</span> <span class="o">=</span> <span class="nv">$storeTransfer</span><span class="o">-&gt;</span><span class="nf">getGdprContactEmail</span><span class="p">();</span> <span class="nv">$resource</span><span class="o">-&gt;</span><span class="n">vatRegistrationNumber</span> <span class="o">=</span> <span class="nv">$storeTransfer</span><span class="o">-&gt;</span><span class="nf">getVatRegistrationNumber</span><span class="p">();</span> <span class="p">}</span> <span class="nv">$resources</span><span class="p">[]</span> <span class="o">=</span> <span class="nv">$resource</span><span class="p">;</span> <span class="p">}</span> <span class="k">return</span> <span class="nv">$resources</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h2 id="schema-layering-with-codebuckets">Schema layering with CodeBuckets</h2> <p>CodeBucket variants are a <strong>project-level concept only</strong> — they never exist in the core (vendor) or feature layers. Core and feature layers contribute properties to the <strong>base</strong> resource. The project-level CodeBucket variant then inherits from that already-merged base and adds its own properties on top.</p> <section class='info-block '><i class='info-block__icon icon-info'></i><div class='info-block__content'><div class="info-block__title">Where CodeBucket files live</div> <p>The <code>codeBucket:</code> property is only ever set in files under <code>src/Pyz/Glue/{Module}{CodeBucketName}/...</code>. A schema file in <code>vendor/spryker/...</code> or <code>src/SprykerFeature/...</code> must not declare a <code>codeBucket:</code> — those layers always describe the base resource.</p> </div></section> <h3 id="example-base-resource-built-across-layers--project-level-eu-variant">Example: base resource built across layers + project-level EU variant</h3> <p>The base <code>Stores</code> resource is assembled from the core, feature, and project layers in that precedence order. The EU variant lives only in the project layer, in its own variant module.</p> <p><strong>Core layer</strong> (vendor) — base only, no <code>codeBucket</code>:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># vendor/spryker/store/resources/api/backend/stores.resource.yml</span> <span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Stores</span> <span class="na">shortName</span><span class="pi">:</span> <span class="s">stores</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">timezone</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> </code></pre></div></div> <p><strong>Feature layer</strong> — base only, no <code>codeBucket</code>:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># src/SprykerFeature/CRM/resources/api/backend/stores.resource.yml</span> <span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Stores</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">countries</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">array</span> </code></pre></div></div> <p><strong>Project base layer</strong> — base only, no <code>codeBucket</code>:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># src/Pyz/Glue/StoresApi/resources/api/backend/stores.resource.yml</span> <span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Stores</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">timezone</span><span class="pi">:</span> <span class="na">required</span><span class="pi">:</span> <span class="no">true</span> <span class="c1"># tighten the core definition</span> </code></pre></div></div> <p><strong>Project CodeBucket variant</strong> — only this file carries <code>codeBucket:</code>:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># src/Pyz/Glue/StoresApiEU/resources/api/backend/stores.resource.yml</span> <span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Stores</span> <span class="na">codeBucket</span><span class="pi">:</span> <span class="s">EU</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">taxRate</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">number</span> <span class="na">required</span><span class="pi">:</span> <span class="no">true</span> <span class="c1"># EU-specific addition</span> <span class="na">companyVatId</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="c1"># EU-specific addition</span> </code></pre></div></div> <p><strong>Merged result</strong> (<code>StoresEUBackendResource</code>) — base properties inherited from the core → feature → project merge, EU-specific properties added on top:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Stores</span> <span class="na">codeBucket</span><span class="pi">:</span> <span class="s">EU</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="c1"># from core</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">timezone</span><span class="pi">:</span> <span class="c1"># from core, tightened by project base</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">required</span><span class="pi">:</span> <span class="no">true</span> <span class="na">countries</span><span class="pi">:</span> <span class="c1"># from feature</span> <span class="na">type</span><span class="pi">:</span> <span class="s">array</span> <span class="na">taxRate</span><span class="pi">:</span> <span class="c1"># from project EU variant</span> <span class="na">type</span><span class="pi">:</span> <span class="s">number</span> <span class="na">required</span><span class="pi">:</span> <span class="no">true</span> <span class="na">companyVatId</span><span class="pi">:</span> <span class="c1"># from project EU variant</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> </code></pre></div></div> <h2 id="fallback-behavior">Fallback behavior</h2> <h3 id="graceful-degradation">Graceful degradation</h3> <p>When <code>APPLICATION_CODE_BUCKET</code> is set but no matching variant exists, the system falls back to the base resource:</p> <pre><code class="language-MARKDOWN">>Scenario: APPLICATION_CODE_BUCKET = 'AT' Available resources: - StoresBackendResource (base) - StoresEUBackendResource (EU variant) Result: StoresBackendResource is used (graceful fallback) No errors, system continues to work </code></pre> <h3 id="no-codebucket-set">No CodeBucket set</h3> <p>When <code>APPLICATION_CODE_BUCKET</code> is not set:</p> <pre><code class="language-MARKDOWN">>Available resources: - StoresBackendResource (base) - StoresEUBackendResource (EU variant) - StoresATBackendResource (AT variant) Result: StoresBackendResource is used All CodeBucket variants are excluded from resource collection </code></pre> <h2 id="resource-collection-filtering">Resource collection filtering</h2> <h3 id="codebucketresourcenamecollectionfactory">CodeBucketResourceNameCollectionFactory</h3> <p>This decorator filters the resource collection at compile time to prevent conflicts between base and CodeBucket variants.</p> <p><strong>When APPLICATION_CODE_BUCKET is not set:</strong></p> <ul> <li>Include all base resources (no CODE_BUCKET constant)</li> <li>Exclude all CodeBucket variants</li> </ul> <p><strong>When APPLICATION_CODE_BUCKET is set (example: ‘EU’):</strong></p> <ol> <li>Group resources by base class name</li> <li>For each group: <ul> <li>If EU variant exists → include ONLY the EU variant</li> <li>If no EU variant exists → include base resource (fallback)</li> <li>Exclude all non-matching CodeBucket variants</li> </ul> </li> </ol> <p><strong>Example filtering:</strong></p> <pre><code class="language-MARKDOWN">>Available classes: - StoresBackendResource (base) - StoresEUBackendResource (EU) - StoresATBackendResource (AT) - CustomersBackendResource (base, no variants) With APPLICATION_CODE_BUCKET = 'EU': ✓ StoresEUBackendResource (EU variant exists) ✗ StoresBackendResource (excluded, EU variant preferred) ✗ StoresATBackendResource (excluded, wrong CodeBucket) ✓ CustomersBackendResource (no variant, base used) With APPLICATION_CODE_BUCKET = 'DE': ✓ StoresBackendResource (no DE variant, fallback to base) ✗ StoresEUBackendResource (excluded, wrong CodeBucket) ✗ StoresATBackendResource (excluded, wrong CodeBucket) ✓ CustomersBackendResource (no variant, base used) </code></pre> <h3 id="benefits-of-filtering">Benefits of filtering</h3> <ul> <li><strong>OpenAPI Generation</strong>: Only the correct variant appears in OpenAPI documentation</li> <li><strong>Route Registration</strong>: Only the correct variant routes are registered</li> <li><strong>No Conflicts</strong>: Base and CodeBucket variants never coexist in routing</li> <li><strong>Performance</strong>: Filtering happens once and is cached</li> </ul> <h2 id="container-compilation">Container compilation</h2> <h3 id="single-container-for-all-codebuckets">Single container for all CodeBuckets</h3> <p>API Platform compiles a single container that contains ALL resources (base and all CodeBucket variants). Runtime resolution selects the correct variant per request.</p> <p><strong>At compile time:</strong></p> <ol> <li>Discover all resource classes in <code>src/Generated/Api/{ApiType}/</code></li> <li>Build metadata for ALL resources (base + all CodeBucket variants)</li> <li>Register routes for ALL resources (all map to same URLs)</li> <li>Cache everything</li> </ol> <p><strong>At runtime:</strong></p> <ol> <li>CodeBucket decorators intercept resolution</li> <li>Select correct resource based on <code>APPLICATION_CODE_BUCKET</code></li> <li>Only selected resource is used for that request</li> <li>Different CodeBuckets served from same container</li> </ol> <h3 id="performance-characteristics">Performance characteristics</h3> <ul> <li><strong>One-time cost</strong>: Container compilation happens once</li> <li><strong>No overhead</strong>: Runtime resolution uses local cache per request</li> <li><strong>Scalability</strong>: Supports hundreds of CodeBuckets without performance impact</li> </ul> <h2 id="debugging-codebucket-resources">Debugging CodeBucket resources</h2> <h3 id="verify-codebucket-constant-generation">Verify CODE_BUCKET constant generation</h3> <p>After regenerating resources, verify the constant was added:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Check EU resource has constant</span> <span class="nb">grep</span> <span class="s2">"CODE_BUCKET"</span> src/Generated/Api/Backend/StoresEUBackendResource.php <span class="c"># Expected: public const string CODE_BUCKET = 'EU';</span> <span class="c"># Verify base resource has no constant</span> <span class="nb">grep</span> <span class="s2">"CODE_BUCKET"</span> src/Generated/Api/Backend/StoresBackendResource.php <span class="c"># Expected: no match (empty output)</span> </code></pre></div></div> <h3 id="debug-resource-resolution">Debug resource resolution</h3> <p>Use the debug command to inspect which resources are available:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># List all resources</span> docker/sdk cli <span class="nv">GLUE_APPLICATION</span><span class="o">=</span>GLUE_BACKEND glue api:debug <span class="nt">--list</span> <span class="c"># Show specific resource</span> docker/sdk cli <span class="nv">GLUE_APPLICATION</span><span class="o">=</span>GLUE_BACKEND glue api:debug stores <span class="nt">--api-type</span><span class="o">=</span>backend <span class="c"># Show merged schema</span> docker/sdk cli <span class="nv">GLUE_APPLICATION</span><span class="o">=</span>GLUE_BACKEND glue api:debug stores <span class="nt">--api-type</span><span class="o">=</span>backend <span class="nt">--show-merged</span> <span class="c"># Show all contributing source files</span> docker/sdk cli <span class="nv">GLUE_APPLICATION</span><span class="o">=</span>GLUE_BACKEND glue api:debug stores <span class="nt">--api-type</span><span class="o">=</span>backend <span class="nt">--show-sources</span> </code></pre></div></div> <h3 id="verify-runtime-resolution">Verify runtime resolution</h3> <p>Test different CodeBuckets by accessing different domains:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Test EU CodeBucket</span> curl <span class="nt">-X</span> GET http://glue-backend.eu.spryker.local/stores <span class="c"># Should include: taxRate, gdprContactEmail, vatRegistrationNumber</span> <span class="c"># Test AT CodeBucket (if no AT variant exists)</span> curl <span class="nt">-X</span> GET http://glue-backend.at.spryker.local/stores <span class="c"># Should return base resource (fallback)</span> <span class="c"># Test DE CodeBucket</span> curl <span class="nt">-X</span> GET http://glue-backend.de.spryker.local/stores <span class="c"># Should return base resource or DE-specific variant if available</span> </code></pre></div></div> <h2 id="best-practices">Best practices</h2> <h3 id="keep-base-resources-complete">1. Keep base resources complete</h3> <p>The base resource should contain all common properties that work across all CodeBuckets:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># ✅ Good - Base is complete</span> <span class="c1"># src/Pyz/Glue/StoresApi/resources/api/backend/stores.resource.yml</span> <span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Stores</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">idStore</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">integer</span> <span class="na">name</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">timezone</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> </code></pre></div></div> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># ✅ EU variant lives in its own module directory</span> <span class="c1"># src/Pyz/Glue/StoresApiEU/resources/api/backend/stores.resource.yml</span> <span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Stores</span> <span class="na">codeBucket</span><span class="pi">:</span> <span class="s">EU</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">idStore</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">integer</span> <span class="na">name</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">timezone</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">taxRate</span><span class="pi">:</span> <span class="c1"># EU-specific addition</span> <span class="na">type</span><span class="pi">:</span> <span class="s">number</span> </code></pre></div></div> <h3 id="use-codebuckets-for-true-regional-differences">2. Use CodeBuckets for true regional differences</h3> <p>Only create CodeBucket variants when there are genuine regional requirements:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># ✅ Good use cases:</span> <span class="pi">-</span> <span class="s">EU GDPR compliance fields</span> <span class="pi">-</span> <span class="s">Code Bucket-specific tax calculations</span> <span class="pi">-</span> <span class="s">Country-specific validation rules</span> <span class="pi">-</span> <span class="s">Code Bucket-specific business logic</span> <span class="c1"># ❌ Bad use cases:q</span> <span class="pi">-</span> <span class="s">Language translations (use locales instead)</span> <span class="pi">-</span> <span class="s">Minor field variations (use base resource)</span> <span class="pi">-</span> <span class="s">Temporary feature flags (use feature toggles)</span> </code></pre></div></div> <h3 id="share-provider-and-processor-logic">3. Share Provider and Processor logic</h3> <p>Use the same Provider and Processor classes for base and CodeBucket variants when possible:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Both use same implementation</span> <span class="na">resource</span><span class="pi">:</span> <span class="na">provider</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Pyz</span><span class="se">\\</span><span class="s">Glue</span><span class="se">\\</span><span class="s">StoresApi</span><span class="se">\\</span><span class="s">Api</span><span class="se">\\</span><span class="s">Backend</span><span class="se">\\</span><span class="s">Provider</span><span class="se">\\</span><span class="s">StoreBackendProvider"</span> <span class="na">processor</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Pyz</span><span class="se">\\</span><span class="s">Glue</span><span class="se">\\</span><span class="s">StoresApi</span><span class="se">\\</span><span class="s">Api</span><span class="se">\\</span><span class="s">Backend</span><span class="se">\\</span><span class="s">Processor</span><span class="se">\\</span><span class="s">StoreBackendProcessor"</span> </code></pre></div></div> <p>Detect the resource type inside the Provider using the <code>CODE_BUCKET</code> constant:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$resourceClass</span> <span class="o">=</span> <span class="nv">$operation</span><span class="o">-&gt;</span><span class="nf">getClass</span><span class="p">();</span> <span class="k">if</span> <span class="p">(</span><span class="nb">defined</span><span class="p">(</span><span class="s2">"</span><span class="nv">$resourceClass</span><span class="s2">::CODE_BUCKET"</span><span class="p">))</span> <span class="p">{</span> <span class="nv">$codeBucket</span> <span class="o">=</span> <span class="nv">$resourceClass</span><span class="o">::</span><span class="no">CODE_BUCKET</span><span class="p">;</span> <span class="c1">// Apply CodeBucket-specific logic</span> <span class="p">}</span> </code></pre></div></div> <h3 id="document-codebucket-specific-fields">4. Document CodeBucket-specific fields</h3> <p>Clearly document which fields are CodeBucket-specific in your schema descriptions:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">gdprContactEmail</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">GDPR</span><span class="nv"> </span><span class="s">contact</span><span class="nv"> </span><span class="s">email</span><span class="nv"> </span><span class="s">(EU-specific</span><span class="nv"> </span><span class="s">requirement</span><span class="nv"> </span><span class="s">for</span><span class="nv"> </span><span class="s">GDPR</span><span class="nv"> </span><span class="s">compliance)"</span> </code></pre></div></div> <h3 id="test-fallback-behavior">5. Test fallback behavior</h3> <p>Always test that your application works correctly when:</p> <ul> <li>CodeBucket is not set (uses base resource)</li> <li>CodeBucket is set but variant doesn’t exist (falls back to base)</li> <li>CodeBucket variant exists (uses variant)</li> </ul> <h2 id="testing">Testing</h2> <p>CodeBucket resources can be tested using the standard API Platform testing infrastructure. The test environment automatically generates resources before tests execute.</p> <p>For detailed testing guidance, see <a href="/docs/dg/dev/architecture/api-platform/testing.html">API Platform Testing</a>.</p> <h2 id="troubleshooting">Troubleshooting</h2> <h3 id="resource-not-found-for-codebucket">Resource not found for CodeBucket</h3> <p>If you get a “Resource not found” error for a specific CodeBucket:</p> <ol> <li>Verify the schema file naming: <code>{resource-name}.resource.yml</code> for resources, <code>{resource-name}.validation.yml</code> for validations</li> <li>Verify the CodeBucket is defined inside the schema file</li> <li>Regenerate resources: <code>docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate backend</code></li> <li>Verify the CODE_BUCKET constant exists in the generated class</li> <li>Check that <code>APPLICATION_CODE_BUCKET</code> matches the CodeBucket defined in your schema file</li> </ol> <h3 id="wrong-resource-variant-used">Wrong resource variant used</h3> <p>If the wrong variant is being used:</p> <ol> <li>Verify <code>APPLICATION_CODE_BUCKET</code> is set correctly in your environment</li> <li>Clear caches: <code>docker/sdk cli rm -rf data/cache/*</code></li> <li>Check that the resource class name follows the pattern: <code>{Name}{CodeBucket}{ApiType}Resource</code></li> <li>Verify the CODE_BUCKET constant value matches <code>APPLICATION_CODE_BUCKET</code></li> </ol> <p>For more troubleshooting guidance, see <a href="/docs/dg/dev/architecture/api-platform/troubleshooting.html">API Platform Troubleshooting</a>.</p> <h2 id="next-steps">Next steps</h2> <ul> <li><a href="/docs/dg/dev/architecture/api-platform/resource-schemas.html">Resource Schemas</a> - Deep dive into schema syntax</li> <li><a href="/docs/dg/dev/architecture/api-platform/validation-schemas.html">Validation Schemas</a> - Define validation rules</li> <li><a href="/docs/dg/dev/architecture/api-platform/enablement.html">API Platform Enablement</a> - Creating resources</li> <li><a href="/docs/dg/dev/architecture/api-platform/testing.html">API Platform Testing</a> - Testing your resources</li> <li><a href="/docs/dg/dev/architecture/api-platform/troubleshooting.html">Troubleshooting</a> - Common issues</li> </ul> Tue, 19 May 2026 12:29:11 +0000 https://docs.spryker.com/docs/dg/dev/architecture/api-platform/code-buckets.html https://docs.spryker.com/docs/dg/dev/architecture/api-platform/code-buckets.html <p>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.</p> <p>This document describes the API Platform architecture and how it integrates with Spryker.</p> <h2 id="what-is-api-platform">What is API Platform</h2> <p>API Platform is a framework for building modern APIs based on web standards and best practices. In Spryker, it complements the existing Glue API infrastructure by providing:</p> <ul> <li><strong>Schema-based resource generation</strong>: Define resources in YAML, generate PHP classes automatically</li> <li><strong>Automatic OpenAPI documentation</strong>: Interactive API documentation generated from schemas</li> <li><strong>Built-in validation</strong>: Symfony Validator integration with operation-specific rules</li> <li><strong>Pagination support</strong>: Standardized pagination with configurable defaults</li> <li><strong>State management</strong>: Separate providers (read) and processors (write) for clean architecture</li> </ul> <p>Read more about the API Platform project at <a href="https://api-platform.com/">api-platform.com</a>.</p> <h2 id="architecture-overview">Architecture overview</h2> <h3 id="resource-generation-workflow">Resource generation workflow</h3> <pre><code class="language-MARKDOWN">>Schema Files (YAML) ↓ Schema Discovery &amp; Validation ↓ Multi-layer Schema Merging (Core → Feature → Project → [Code Buckets]) ↓ Resource Class Generation ↓ API Platform Resource (with attributes) ↓ API Endpoints </code></pre> <h3 id="core-components">Core components</h3> <h4 id="schema-files">1. Schema files</h4> <p>Resources are defined in YAML files located in module directories:</p> <pre><code class="language-MARKDOWN">>src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.resources.yml src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.validation.yml </code></pre> <p>Example resource schema <code>src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.resources.yml</code>:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Customers</span> <span class="na">shortName</span><span class="pi">:</span> <span class="s">customers</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Customer</span><span class="nv"> </span><span class="s">resource</span><span class="nv"> </span><span class="s">for</span><span class="nv"> </span><span class="s">backend</span><span class="nv"> </span><span class="s">API"</span> <span class="na">provider</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Pyz</span><span class="se">\\</span><span class="s">Glue</span><span class="se">\\</span><span class="s">Customer</span><span class="se">\\</span><span class="s">Api</span><span class="se">\\</span><span class="s">Backend</span><span class="se">\\</span><span class="s">Provider</span><span class="se">\\</span><span class="s">CustomerBackendProvider"</span> <span class="na">processor</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Pyz</span><span class="se">\\</span><span class="s">Glue</span><span class="se">\\</span><span class="s">Customer</span><span class="se">\\</span><span class="s">Api</span><span class="se">\\</span><span class="s">Backend</span><span class="se">\\</span><span class="s">Processor</span><span class="se">\\</span><span class="s">CustomerBackendProcessor"</span> <span class="na">paginationEnabled</span><span class="pi">:</span> <span class="no">true</span> <span class="na">operations</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Post</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Get</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">GetCollection</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Patch</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Delete</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">email</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">description</span><span class="pi">:</span> <span class="s2">"</span><span class="s">Customer</span><span class="nv"> </span><span class="s">email</span><span class="nv"> </span><span class="s">address"</span> <span class="na">customerReference</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="na">identifier</span><span class="pi">:</span> <span class="no">true</span> <span class="na">writable</span><span class="pi">:</span> <span class="no">false</span> </code></pre></div></div> <p>Example validation schema <code>src/Spryker/{Module}/resources/api/{api-type}/{resource-name}.validation.yml</code>:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">post</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">NotBlank</span><span class="pi">:</span> <span class="na">message</span><span class="pi">:</span> <span class="s">First name is required</span> <span class="pi">-</span> <span class="na">Length</span><span class="pi">:</span> <span class="na">min</span><span class="pi">:</span> <span class="m">2</span> <span class="na">max</span><span class="pi">:</span> <span class="m">64</span> <span class="na">minMessage</span><span class="pi">:</span> <span class="s">First name must be at least 2 characters</span> <span class="na">maxMessage</span><span class="pi">:</span> <span class="s">First name cannot exceed 64 characters</span> <span class="na">patch</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">Optional</span><span class="pi">:</span> <span class="na">constraints</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">Length</span><span class="pi">:</span> <span class="na">min</span><span class="pi">:</span> <span class="m">2</span> <span class="na">max</span><span class="pi">:</span> <span class="m">64</span> <span class="na">minMessage</span><span class="pi">:</span> <span class="s">First name must be at least 2 characters</span> <span class="na">maxMessage</span><span class="pi">:</span> <span class="s">First name cannot exceed 64 characters</span> </code></pre></div></div> <h4 id="generated-resources">2. Generated resources</h4> <p>The generator creates PHP classes with API Platform attributes:</p> <p><code>src/Generated/Api/Backend/CustomersBackendResource.php</code></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span> <span class="kn">namespace</span> <span class="nn">Generated\Api\Backend</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ApiPlatform\Metadata\ApiResource</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">ApiPlatform\Metadata\ApiProperty</span><span class="p">;</span> <span class="kn">use</span> <span class="nc">Symfony\Component\Validator\Constraints</span> <span class="k">as</span> <span class="nc">Assert</span><span class="p">;</span> <span class="c1">#[ApiResource(</span> <span class="n">operations</span><span class="o">:</span> <span class="p">[</span><span class="k">new</span> <span class="nc">Post</span><span class="p">(),</span> <span class="k">new</span> <span class="nc">Get</span><span class="p">(),</span> <span class="k">new</span> <span class="nc">GetCollection</span><span class="p">(),</span> <span class="k">new</span> <span class="nc">Patch</span><span class="p">(),</span> <span class="k">new</span> <span class="nc">Delete</span><span class="p">()],</span> <span class="n">shortName</span><span class="o">:</span> <span class="s1">'customers'</span><span class="p">,</span> <span class="n">provider</span><span class="o">:</span> <span class="nc">CustomerBackendProvider</span><span class="o">::</span><span class="n">class</span><span class="p">,</span> <span class="n">processor</span><span class="o">:</span> <span class="nc">CustomerBackendProcessor</span><span class="o">::</span><span class="n">class</span> <span class="p">)]</span> <span class="k">final</span> <span class="kd">class</span> <span class="nc">CustomersBackendResource</span> <span class="p">{</span> <span class="c1">#[ApiProperty(identifier: true, writable: false)]</span> <span class="k">public</span> <span class="kt">?string</span> <span class="nv">$customerReference</span> <span class="o">=</span> <span class="kc">null</span><span class="p">;</span> <span class="c1">#[ApiProperty]</span> <span class="c1">#[Assert\NotBlank(groups: ['customers:create'])]</span> <span class="c1">#[Assert\Email(groups: ['customers:create'])]</span> <span class="k">public</span> <span class="kt">?string</span> <span class="nv">$email</span> <span class="o">=</span> <span class="kc">null</span><span class="p">;</span> <span class="c1">// Getters, setters, toArray(), fromArray()...</span> <span class="p">}</span> </code></pre></div></div> <h4 id="state-providers-and-processors">3. State providers and processors</h4> <p>Detailed information about the API-Platform Provider and Resources can be found on the public docs:</p> <ul> <li><a href="https://api-platform.com/docs/core/state-providers/">API Platform Providers</a></li> <li><a href="https://api-platform.com/docs/core/state-processors/">API Platform Processors</a></li> </ul> <p><strong>Provider (read operations):</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">class</span> <span class="nc">CustomerBackendProvider</span> <span class="kd">implements</span> <span class="nc">ProviderInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">provide</span><span class="p">(</span><span class="kt">Operation</span> <span class="nv">$operation</span><span class="p">,</span> <span class="kt">array</span> <span class="nv">$uriVariables</span> <span class="o">=</span> <span class="p">[],</span> <span class="kt">array</span> <span class="nv">$context</span> <span class="o">=</span> <span class="p">[]):</span> <span class="kt">object</span><span class="o">|</span><span class="k">array</span><span class="o">|</span><span class="kc">null</span> <span class="p">{</span> <span class="c1">// Fetch and return data from your business layer</span> <span class="k">return</span> <span class="nv">$customerResource</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <p><strong>Processor (write operations):</strong></p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">class</span> <span class="nc">CustomerBackendProcessor</span> <span class="kd">implements</span> <span class="nc">ProcessorInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">process</span><span class="p">(</span><span class="kt">mixed</span> <span class="nv">$data</span><span class="p">,</span> <span class="kt">Operation</span> <span class="nv">$operation</span><span class="p">,</span> <span class="kt">array</span> <span class="nv">$uriVariables</span> <span class="o">=</span> <span class="p">[],</span> <span class="kt">array</span> <span class="nv">$context</span> <span class="o">=</span> <span class="p">[]):</span> <span class="kt">mixed</span> <span class="p">{</span> <span class="c1">// Persist changes through your business layer</span> <span class="k">return</span> <span class="nv">$updatedResource</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h2 id="api-types">API types</h2> <p>Any of the <a href="https://docs.spryker.com/docs/integrations/spryker-glue-api/getting-started-with-apis/getting-started-with-apis">existing APIs</a> can be extended using API Platform.</p> <p>Spryker supports multiple API types for different use cases:</p> <h3 id="glue-api">Glue API</h3> <p>This API is configured to serve the JSON:API format by default, which can be configured per project. Projects migrating their APIs can provide new APIs as well as supporting the existing ones while migrating.</p> <ul> <li><strong>API Type:</strong> <code>storefront</code></li> <li><strong>Application:</strong> Glue</li> <li><strong>Base URL:</strong> <code>http://glue.eu.spryker.local/</code> - Configurable per project</li> <li><strong>Use cases:</strong> Customer-facing APIs, mobile apps, PWAs</li> </ul> <h3 id="gluestorefront-api">GlueStorefront API</h3> <p>Thie API is configured to serve the JSON+LD format by default, which can be configured per project.</p> <ul> <li><strong>API Type:</strong> <code>storefront</code></li> <li><strong>Application:</strong> Glue</li> <li><strong>Base URL:</strong> <code>http://glue-storefront.eu.spryker.local/</code> - Configurable per project</li> <li><strong>Use cases:</strong> Customer-facing APIs, mobile apps, PWAs</li> </ul> <h3 id="gluebackend-api">GlueBackend API</h3> <ul> <li><strong>API Type:</strong> <code>backend</code></li> <li><strong>Application:</strong> Zed</li> <li><strong>Base URL:</strong> <code>http://glue-backend.eu.spryker.local/</code></li> <li><strong>Use cases:</strong> Admin panels, internal tools, ERP integrations</li> </ul> <h3 id="merchant-portal-api">Merchant Portal API</h3> <ul> <li><strong>API Type:</strong> <code>merchant-portal</code></li> <li><strong>Application:</strong> MerchantPortal</li> <li><strong>Base URL:</strong> <code>http://mp.glue.eu.spryker.local/</code></li> <li><strong>Use cases:</strong> Marketplace merchant interfaces</li> <li><strong>Example:</strong> <code>/products</code></li> </ul> <h2 id="multi-layer-schema-merging">Multi-layer schema merging</h2> <p>One of the key features is support for multi-layer schema definitions that automatically merge:</p> <p><strong>Core layer</strong> (vendor/spryker):</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Customers</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">email</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> </code></pre></div></div> <p><strong>Feature layer</strong> (src/SprykerFeature):</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Customers</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">loyaltyPoints</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">integer</span> </code></pre></div></div> <p><strong>Project layer</strong> (src/Pyz):</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">resource</span><span class="pi">:</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Customers</span> <span class="na">properties</span><span class="pi">:</span> <span class="na">email</span><span class="pi">:</span> <span class="na">required</span><span class="pi">:</span> <span class="no">true</span> <span class="c1"># Override core</span> <span class="na">customField</span><span class="pi">:</span> <span class="na">type</span><span class="pi">:</span> <span class="s">string</span> <span class="c1"># Project-specific</span> </code></pre></div></div> <p><strong>Result</strong>: A single merged resource with all properties, project code-bucket layer taking precedence.</p> <h2 id="integration-with-spryker-architecture">Integration with Spryker architecture</h2> <h3 id="dependency-injection">Dependency Injection</h3> <p>API Platform fully integrates with Symfony Dependency Injection:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// config/Zed/ApplicationServices.php</span> <span class="nv">$services</span><span class="o">-&gt;</span><span class="nf">load</span><span class="p">(</span><span class="s1">'Pyz\\Zed\\'</span><span class="p">,</span> <span class="s1">'../../../src/Pyz/Zed/'</span><span class="p">);</span> </code></pre></div></div> <p>Providers and Processors are automatically discovered and can use constructor injection:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">class</span> <span class="nc">CustomerBackofficeProvider</span> <span class="kd">implements</span> <span class="nc">ProviderInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">__construct</span><span class="p">(</span> <span class="k">private</span> <span class="kt">CustomerFacadeInterface</span> <span class="nv">$customerFacade</span><span class="p">,</span> <span class="k">private</span> <span class="kt">CustomerRepositoryInterface</span> <span class="nv">$customerRepository</span><span class="p">,</span> <span class="p">)</span> <span class="p">{}</span> <span class="p">}</span> </code></pre></div></div> <h3 id="facade-integration">Facade integration</h3> <p>Resources can leverage existing Spryker facades:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">class</span> <span class="nc">CustomerBackendProcessor</span> <span class="kd">implements</span> <span class="nc">ProcessorInterface</span> <span class="p">{</span> <span class="k">public</span> <span class="k">function</span> <span class="n">__construct</span><span class="p">(</span> <span class="k">private</span> <span class="kt">CustomerFacadeInterface</span> <span class="nv">$customerFacade</span><span class="p">,</span> <span class="p">)</span> <span class="p">{}</span> <span class="k">public</span> <span class="k">function</span> <span class="n">process</span><span class="p">(</span><span class="kt">mixed</span> <span class="nv">$data</span><span class="p">,</span> <span class="kt">Operation</span> <span class="nv">$operation</span><span class="p">,</span> <span class="p">...):</span> <span class="kt">mixed</span> <span class="p">{</span> <span class="nv">$customerTransfer</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">mapToTransfer</span><span class="p">(</span><span class="nv">$data</span><span class="p">);</span> <span class="nv">$response</span> <span class="o">=</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">customerFacade</span><span class="o">-&gt;</span><span class="nf">createCustomer</span><span class="p">(</span><span class="nv">$customerTransfer</span><span class="p">);</span> <span class="k">return</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="nf">mapToResource</span><span class="p">(</span><span class="nv">$response</span><span class="o">-&gt;</span><span class="nf">getCustomerTransfer</span><span class="p">());</span> <span class="p">}</span> <span class="p">}</span> </code></pre></div></div> <h2 id="resource-generation">Resource generation</h2> <h3 id="console-commands">Console commands</h3> <p>All the following commands can be used with a specific GLUE_APPLICATION by prefixing them with <code>GLUE_APPLICATION=GLUE_BACKEND</code> environment variable. For example: <code>docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:debug --list</code></p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Generate resource classes for all configured API types at once. Usually used during deployment/installation.</span> docker/sdk cli glue api:generate <span class="c"># Generate API type specific resource classes. Usually used during development.</span> docker/sdk cli glue api:generate backend <span class="c"># Validate schemas only to see if there is any issue in the definitions</span> docker/sdk cli glue api:generate <span class="nt">--validate-only</span> </code></pre></div></div> <h3 id="debug-commands">Debug commands</h3> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># List all resources to see which ones are defined in the schema files.</span> docker/sdk cli glue api:debug <span class="nt">--list</span> <span class="c"># Inspect specific resource and print details about properties and operations</span> docker/sdk cli glue api:debug customers <span class="nt">--api-type</span><span class="o">=</span>backend <span class="c"># Show merged schema</span> docker/sdk cli glue api:debug customers <span class="nt">--api-type</span><span class="o">=</span>backend <span class="nt">--show-merged</span> <span class="c"># Show contributing files for a resource</span> docker/sdk cli glue api:debug customers <span class="nt">--api-type</span><span class="o">=</span>backend <span class="nt">--show-sources</span> </code></pre></div></div> <h2 id="features">Features</h2> <h3 id="automatic-openapi-documentation">Automatic OpenAPI documentation</h3> <p>API Platform generates interactive OpenAPI documentation:</p> <ul> <li>Swagger UI at the root URL <code>/</code> for example <code>http://glue-backend.eu.spryker.local/</code></li> </ul> <p>You can disable this interface in production environments by configuring the settings in your <code>api_platform.php</code> configuration file. For details, see <a href="/docs/dg/dev/architecture/api-platform/configuration.html#disable-swaggerui-in-production">Disable Swagger UI</a>.</p> <h3 id="built-in-validation">Built-in validation</h3> <p>Validation rules from <code>*.validation.yml</code> files are converted to Symfony Validator constraints:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">post</span><span class="pi">:</span> <span class="na">email</span><span class="pi">:</span> <span class="pi">-</span> <span class="s">NotBlank</span> <span class="pi">-</span> <span class="s">Email</span> </code></pre></div></div> <p>Becomes:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">#[Assert\NotBlank(groups: ['customers:create'])]</span> <span class="c1">#[Assert\Email(groups: ['customers:create'])]</span> <span class="k">public</span> <span class="kt">?string</span> <span class="nv">$email</span> <span class="o">=</span> <span class="kc">null</span><span class="p">;</span> </code></pre></div></div> <h3 id="pagination-support">Pagination support</h3> <p>Standardized pagination with query parameters:</p> <pre><code class="language-MARKDOWN">>GET /customers?page=2&amp;itemsPerPage=20 </code></pre> <p>Provider returns <code>PaginatorInterface</code>:</p> <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">return</span> <span class="k">new</span> <span class="nc">TraversablePaginator</span><span class="p">(</span> <span class="k">new</span> <span class="err">\</span><span class="nf">ArrayObject</span><span class="p">(</span><span class="nv">$results</span><span class="p">),</span> <span class="nv">$currentPage</span><span class="p">,</span> <span class="nv">$itemsPerPage</span><span class="p">,</span> <span class="nv">$totalItems</span> <span class="p">);</span> </code></pre></div></div> <h3 id="operation-specific-behavior">Operation-specific behavior</h3> <p>Define different validation and behavior per operation:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">operations</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Post</span> <span class="c1"># Create</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Get</span> <span class="c1"># Read one</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">GetCollection</span> <span class="c1"># Read many</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Patch</span> <span class="c1"># Update</span> <span class="pi">-</span> <span class="na">type</span><span class="pi">:</span> <span class="s">Delete</span> <span class="c1"># Delete</span> </code></pre></div></div> <p>Each operation can have specific validation rules and security settings.</p> <h3 id="relationships">Relationships</h3> <p>Include related resources via the <code>?include=</code> query parameter:</p> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">includes</span><span class="pi">:</span> <span class="pi">-</span> <span class="na">relationshipName</span><span class="pi">:</span> <span class="s">addresses</span> <span class="na">targetResource</span><span class="pi">:</span> <span class="s">CustomersAddresses</span> <span class="na">uriVariableMappings</span><span class="pi">:</span> <span class="na">customerReference</span><span class="pi">:</span> <span class="s">customerReference</span> </code></pre></div></div> <p>Request:</p> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>GET /customers/customer--35?include=addresses </code></pre></div></div> <p>Response includes both the customer and related addresses in JSON:API format. No provider code changes required - relationships work automatically through decoration.</p> <p>For detailed information, see <a href="/docs/dg/dev/architecture/api-platform/relationships.html">Relationships</a>.</p> <h3 id="sparse-fieldsets">Sparse fieldsets</h3> <p>Request only the attributes you need using the <code>fields</code> query parameter:</p> <div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>GET /stores?fields[stores]=name,locale </code></pre></div></div> <p>This returns only <code>name</code> and <code>locale</code> in the response attributes, reducing payload size. Sparse fieldsets work with relationships too — filter attributes on both the main resource and included resources.</p> <p>For detailed information, see <a href="/docs/dg/dev/architecture/api-platform/sparse-fieldsets.html">Sparse Fieldsets</a>.</p> <h2 id="performance">Performance</h2> <h3 id="cache-warming">Cache warming</h3> <p>Pre-generate resources during deployment:</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>docker/sdk cli glue api:generate </code></pre></div></div> <p>or</p> <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>docker/sdk cli glue cache:warmup </code></pre></div></div> <h3 id="property-level-access-control">Property-level access control</h3> <div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">properties</span><span class="pi">:</span> <span class="na">password</span><span class="pi">:</span> <span class="na">writable</span><span class="pi">:</span> <span class="no">true</span> <span class="c1"># Can be written</span> <span class="na">readable</span><span class="pi">:</span> <span class="no">false</span> <span class="c1"># Not in responses</span> </code></pre></div></div> <h2 id="comparison-with-glue-api">Comparison with Glue API</h2> <table> <thead> <tr> <th>Feature</th> <th>API Platform</th> <th>Glue API</th> </tr> </thead> <tbody> <tr> <td>Definition</td> <td>Schema-based (YAML)</td> <td>Code-based (PHP)</td> </tr> <tr> <td>Documentation</td> <td>Auto-generated OpenAPI</td> <td>Manual</td> </tr> <tr> <td>Validation</td> <td>Declarative</td> <td>Programmatic</td> </tr> <tr> <td>Standards</td> <td>JSON-LD, Hydra</td> <td>JSON API</td> </tr> <tr> <td>Learning curve</td> <td>Lower</td> <td>Higher</td> </tr> <tr> <td>Flexibility</td> <td>High</td> <td>Very high</td> </tr> <tr> <td>Use cases</td> <td>Standard CRUD</td> <td>Complex business logic</td> </tr> </tbody> </table> <p>Both can coexist in the same application. For further migration guidance, see <a href="/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform.html">How to migrate to API Platform</a>.</p> <h2 id="related-documentation">Related documentation</h2> <p>For detailed implementation guides:</p> <ul> <li><a href="/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html">How to integrate API Platform</a> - Setup and configuration</li> <li><a href="/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html">How to integrate API Platform Security</a> - Authentication and authorization setup</li> <li><a href="/docs/dg/dev/upgrade-and-migrate/migrate-to-api-platform.html">How to migrate to API Platform</a> - Migrate endpoints from Glue API</li> <li><a href="/docs/dg/dev/architecture/api-platform/configuration.html">API Platform Configuration</a> - Configure API Platform settings</li> <li><a href="/docs/dg/dev/architecture/api-platform/security.html">Security</a> - Authentication and authorization</li> <li><a href="/docs/dg/dev/architecture/api-platform/enablement.html">API Platform Enablement</a> - Creating your first resource</li> <li><a href="/docs/dg/dev/architecture/api-platform/resource-schemas.html">Resource Schemas</a> - Resource Schemas</li> <li><a href="/docs/dg/dev/architecture/api-platform/validation-schemas.html">Validation Schemas</a> - Validation Schemas</li> <li><a href="/docs/dg/dev/architecture/api-platform/native-api-platform-resources.html">Native API Platform Resources</a> - Using native PHP attributes</li> <li><a href="/docs/dg/dev/architecture/api-platform/code-buckets.html">CodeBucket Support</a> - Region-specific resources</li> <li><a href="/docs/dg/dev/architecture/api-platform/sparse-fieldsets.html">Sparse Fieldsets</a> - Request only needed attributes</li> <li><a href="/docs/dg/dev/architecture/api-platform/troubleshooting.html">Troubleshooting API Platform</a> - Common issues</li> </ul> <h2 id="next-steps">Next steps</h2> <ul> <li><a href="/docs/dg/dev/upgrade-and-migrate/integrate-api-platform.html">How to integrate API Platform</a></li> <li><a href="/docs/dg/dev/upgrade-and-migrate/integrate-api-platform-security.html">How to integrate API Platform Security</a></li> <li><a href="/docs/dg/dev/architecture/api-platform/native-api-platform-resources.html">Native API Platform Resources</a></li> <li><a href="/docs/dg/dev/architecture/api-platform/code-buckets.html">CodeBucket Support in API Platform</a></li> <li><a href="https://api-platform.com/docs/">API Platform official documentation</a></li> </ul> Tue, 19 May 2026 12:29:11 +0000 https://docs.spryker.com/docs/dg/dev/architecture/api-platform.html https://docs.spryker.com/docs/dg/dev/architecture/api-platform.html Keeping your project's Spryker module dependencies up to date is critical for maintaining optimal performance, security, and reducing long-term upgrade efforts. ## Why keep dependencies updated Updating dependencies regularly provides several practical benefits: 1. **Risk of security vulnerabilities**: Most recent versions contain necessary fixes to all known vulnerabilities. 2. **Performance and resource consumption optimizations**: Spryker continuously releases performance improvements based on real-life experiences and scenarios. 3. **Decreasing upgrade efforts**: Distributing upgrades across many smaller steps is much easier than doing one massive upgrade later. ## Key resources The following resources provide information about performance-related module releases: - [Security release notes 202512.0](https://docs.spryker.com/docs/about/all/releases/security-releases/security-release-notes-202512.0.html) - [Release notes 202410.0](https://docs.spryker.com/docs/scos/user/intro-to-spryker/releases/release-notes/release-notes-202410.0/release-notes-202410.0.html) - [Release notes 202507.0](https://docs.spryker.com/docs/scos/user/intro-to-spryker/releases/release-notes/release-notes-202507.0/release-notes-202507.0.html) - [General performance guidelines](/docs/dg/dev/guidelines/performance-guidelines/general-performance-guidelines.html) - contains the list of recent module versions with known performance optimizations - [Cart page performance configuration](https://docs.spryker.com/docs/pbc/all/cart-and-checkout/latest/cart-page-performance-configuration.html) ## Critical module updates The following sections list important module updates that include performance improvements. It's recommended that each Spryker project evaluates and applies these updates. ### Product search performance **spryker/product-page-search** - Recent versions (for example, `3.38.0` - `3.40.0`) include improvements such as: - Caching logic adjustments for product images - Potential bulk operation support to make search document writes more efficient - Avoiding duplicate locale events ### Session management **spryker/session** - at least `^4.17.0` - Provides configurable session locking mechanism - See [Redis session lock](/docs/dg/dev/troubleshooting/troubleshooting-performance-issues/redis-session-lock.html) for configuration details **spryker/session-redis** - at least `^1.11.2` - Includes configurable session locker - See [Redis session lock](/docs/dg/dev/troubleshooting/troubleshooting-performance-issues/redis-session-lock.html) for setup instructions ### Merchant Portal and Back Office performance with ACL rules - [spryker/acl:^3.26.0](https://github.com/spryker/acl/releases/tag/3.26.0) - [spryker/acl-entity:^1.16.0](https://github.com/spryker/acl-entity/releases/tag/1.16.0) - [spryker/gui:^4.11.0](https://github.com/spryker/gui/releases/tag/4.11.0) - [spryker/merchant-profile:^1.9.0](https://github.com/spryker/merchant-profile/releases/tag/1.9.0) - [spryker/merchant-user:^1.9.0](https://github.com/spryker/merchant-user/releases/tag/1.9.0) - [spryker/multi-factor-auth-merchant-portal:^2.1.0](https://github.com/spryker/multi-factor-auth-merchant-portal/releases/tag/2.1.0) - [spryker/product-attribute:^1.18.0](https://github.com/spryker/product-attribute/releases/tag/1.18.0) - [spryker/zed-navigation:^1.15.0](https://github.com/spryker/zed-navigation/releases/tag/1.15.0) ### Back Office performance on category list page - [spryker/product-category:"^4.32.0"](https://github.com/spryker/zed-navigation/releases/tag/4.32.0) ### Order placement performance - [spryker/calculation:^4.14.0](https://github.com/spryker/calculation/releases/tag/4.14.0) - [spryker/discount-calculation-connector:^5.4.0](https://github.com/spryker/discount-calculation-connector/releases/tag/5.4.0) - [spryker/merchant:^3.15.0](https://github.com/spryker/merchant/releases/tag/3.15.0) - [spryker/sales:^11.60.0](https://github.com/spryker/sales/releases/tag/11.60.0) - [spryker/product:^6.49.0](https://github.com/spryker/product/releases/tag/6.49.0) - [spryker/discount:^9.43.0](https://github.com/spryker/discount/releases/tag/9.43.0) - [spryker/product-cart-connector:^4.13.0](https://github.com/spryker/product-cart-connector/releases/tag/4.13.0) - [spryker/company-role:^1.9.1](https://github.com/spryker/company-role/releases/tag/1.9.1) - [spryker/propel:^3.43.0](https://github.com/spryker/propel/releases/tag/3.43.0) - [spryker/sales:^11.63.0](https://github.com/spryker/sales/releases/tag/11.63.0) - [spryker/sales-product-connector:^1.11.1](https://github.com/spryker/sales-product-connector/releases/tag/1.11.1) - [spryker/shipment:^8.24.0](https://github.com/spryker/shipment/releases/tag/8.24.0) ### OMS availability check and order item reservation - [spryker/availability:^9.27.0](https://github.com/spryker/availability/releases/tag/9.27.0) - [spryker/stock:^8.10.1](https://github.com/spryker/stock/releases/tag/8.10.1) - [spryker/oms:^11.45.1](https://github.com/spryker/oms/releases/tag/11.45.1) - [spryker/propel:^3.43.0](https://github.com/spryker/propel/releases/tag/3.43.0) - [spryker/sales:^11.63.0](https://github.com/spryker/sales/releases/tag/11.63.0) ### Publish and synchronization (merchant-related) - [spryker/merchant-product-offer-storage:^2.6.0](https://github.com/spryker/merchant-product-offer-storage/releases/tag/2.6.0) - [spryker/product-offer-storage:^1.8.0](https://github.com/spryker/product-offer-storage/releases/tag/1.8.0) - [spryker/propel:^3.45.0](https://github.com/spryker/propel/releases/tag/3.45.0) ### Publish and synchronization (product-related) - [spryker/price-product:^4.48.0](https://github.com/spryker/price-product/releases/tag/4.48.0) - [spryker/product-page-search:^3.40.0](https://github.com/spryker/product-page-search/releases/tag/3.40.0) - [spryker/product-search:^5.24.1](https://github.com/spryker/product-search/releases/tag/5.24.1) - [spryker/product-storage:^1.47.0](https://github.com/spryker/product-storage/releases/tag/1.47.0) - [spryker/product-offer-storage:^1.10.0](https://github.com/spryker/product-offer-storage/releases/tag/1.10.0) - [spryker/price-product-offer:^1.7.1](https://github.com/spryker/price-product-offer/releases/tag/1.7.1) - [spryker/price-product-offer-storage:^1.5.1](https://github.com/spryker/price-product-offer-storage/releases/tag/1.5.1) - [spryker/price-product-storage:^4.13.0](https://github.com/spryker/price-product-storage/releases/tag/4.13.0) - [spryker/product-image:^3.20.1](https://github.com/spryker/product-image/releases/tag/3.20.1) - [spryker/product-category-storage:^2.11.0](https://github.com/spryker/product-category-storage/releases/tag/2.11.0) - [spryker/product-category-search:^1.2.1](https://github.com/spryker/product-category-search/releases/tag/1.2.1) - [spryker/propel:^3.47.0](https://github.com/spryker/propel/releases/tag/3.47.0) - Note: If you still use destructive deployments, update the `config/install/destructive.yml` file. You can copy it from any demo shop. - [spryker/event-behavior:^1.32.0](https://github.com/spryker/event-behavior/releases/tag/1.32.0) - [spryker/synchronization-behavior:^1.13.0](https://github.com/spryker/synchronization-behavior/releases/tag/1.13.0) ### Publish and synchronization (Category tree build logic) - [spryker/category:"^5.23.0"](https://github.com/spryker/category/releases/tag/5.23.0) - [spryker/category-storage:"^2.12.0"](https://github.com/spryker/category-storage/releases/tag/2.12.0) - [spryker/propel-orm:"^1.22.0"](https://github.com/spryker/propel-orm/releases/tag/1.22.0) - [spryker/util-sanitize:"^2.3.1"](https://github.com/spryker/util-sanitize/releases/tag/2.3.1) ### Publish and synchronization (queue and event performance) To update all required modules at once: ```bash composer update spryker/rabbit-mq:"^2.25.0" spryker/availability-storage:"^2.11.0" spryker/event:"^2.17.1" spryker/glossary-storage:"^1.14.0" spryker/merchant-product:"^1.12.0" spryker/merchant-product-offer:"^1.12.0" spryker/merchant-product-offer-search:"^1.9.0" spryker/merchant-product-search:"^1.6.0" spryker/merchant-product-storage:"^1.7.0" spryker/price-product:"^4.51.0" spryker/price-product-merchant-relationship-storage:"^1.21.0" spryker/price-product-offer-storage:"^1.8.0" spryker/price-product-storage:"^4.16.0" spryker/product:"^6.54.0" spryker/product-category-search:"^1.3.0" spryker/product-category-storage:"^2.13.0" spryker/product-group-storage:"^1.9.0" spryker/product-image:"^3.21.0" spryker/product-image-storage:"^1.21.0" spryker/product-list:"^1.10.0" spryker/product-list-search:"^2.11.0" spryker/product-list-storage:"^1.21.0" spryker/product-offer:"^1.17.0" spryker/product-offer-availability-storage:"^1.6.0" spryker/product-offer-stock:"^1.7.0" spryker/product-page-search:"^3.47.0" spryker/product-page-search-extension:"^1.7.0" spryker/propel:"^3.50.0" spryker/queue:"^1.27.0" spryker/symfony-messenger:"^1.6.0" spryker/tax-product-storage:"^1.8.0" spryker/url-storage:"^1.23.0" spryker/synchronization-behavior:"^1.14.0" ``` - [spryker/rabbit-mq:^2.25.0](https://github.com/spryker/rabbit-mq/releases/tag/2.25.0) - [spryker/availability-storage:^2.11.0](https://github.com/spryker/availability-storage/releases/tag/2.11.0) - [spryker/event:^2.17.1](https://github.com/spryker/event/releases/tag/2.17.1) - [spryker/event-behavior:^1.35.0](https://github.com/spryker/event-behavior/releases/tag/1.35.0) - [spryker/glossary-storage:^1.14.0](https://github.com/spryker/glossary-storage/releases/tag/1.14.0) - [spryker/merchant-product:^1.12.0](https://github.com/spryker/merchant-product/releases/tag/1.12.0) - [spryker/merchant-product-offer:^1.12.0](https://github.com/spryker/merchant-product-offer/releases/tag/1.12.0) - [spryker/merchant-product-offer-search:^1.9.0](https://github.com/spryker/merchant-product-offer-search/releases/tag/1.9.0) - [spryker/merchant-product-search:^1.6.0](https://github.com/spryker/merchant-product-search/releases/tag/1.6.0) - [spryker/merchant-product-storage:^1.7.0](https://github.com/spryker/merchant-product-storage/releases/tag/1.7.0) - [spryker/price-product:^4.51.0](https://github.com/spryker/price-product/releases/tag/4.51.0) - [spryker/price-product-merchant-relationship-storage:^1.21.0](https://github.com/spryker/price-product-merchant-relationship-storage/releases/tag/1.21.0) - [spryker/price-product-offer-storage:^1.8.0](https://github.com/spryker/price-product-offer-storage/releases/tag/1.8.0) - [spryker/price-product-storage:^4.16.0](https://github.com/spryker/price-product-storage/releases/tag/4.16.0) - [spryker/product:^6.54.0](https://github.com/spryker/product/releases/tag/6.54.0) - [spryker/product-category-search:^1.3.0](https://github.com/spryker/product-category-search/releases/tag/1.3.0) - [spryker/product-category-storage:^2.13.0](https://github.com/spryker/product-category-storage/releases/tag/2.13.0) - [spryker/product-group-storage:^1.9.0](https://github.com/spryker/product-group-storage/releases/tag/1.9.0) - [spryker/product-image:^3.21.0](https://github.com/spryker/product-image/releases/tag/3.21.0) - [spryker/product-image-storage:^1.21.0](https://github.com/spryker/product-image-storage/releases/tag/1.21.0) - [spryker/product-list:^1.10.0](https://github.com/spryker/product-list/releases/tag/1.10.0) - [spryker/product-list-search:^2.11.0](https://github.com/spryker/product-list-search/releases/tag/2.11.0) - [spryker/product-list-storage:^1.21.0](https://github.com/spryker/product-list-storage/releases/tag/1.21.0) - [spryker/product-offer:^1.17.0](https://github.com/spryker/product-offer/releases/tag/1.17.0) - [spryker/product-offer-availability-storage:^1.6.0](https://github.com/spryker/product-offer-availability-storage/releases/tag/1.6.0) - [spryker/product-offer-stock:^1.7.0](https://github.com/spryker/product-offer-stock/releases/tag/1.7.0) - [spryker/product-page-search:^3.47.0](https://github.com/spryker/product-page-search/releases/tag/3.47.0) - [spryker/product-page-search-extension:^1.7.0](https://github.com/spryker/product-page-search-extension/releases/tag/1.7.0) - [spryker/propel:^3.50.0](https://github.com/spryker/propel/releases/tag/3.50.0) - [spryker/queue:^1.27.0](https://github.com/spryker/queue/releases/tag/1.27.0) - [spryker/symfony-messenger:^1.6.0](https://github.com/spryker/symfony-messenger/releases/tag/1.6.0) - [spryker/tax-product-storage:^1.8.0](https://github.com/spryker/tax-product-storage/releases/tag/1.8.0) - [spryker/url-storage:^1.23.0](https://github.com/spryker/url-storage/releases/tag/1.23.0) - [spryker/synchronization-behavior:^1.14.0](https://github.com/spryker/synchronization-behavior/releases/tag/1.14.0) ### Data import (memory usage) - [spryker/acl-entity:"^1.17.0"](https://github.com/spryker/acl-entity/releases/tag/1.17.0) - [spryker/data-import:"^1.33.0"](https://github.com/spryker/data-import/releases/tag/1.33.0) - [spryker/merchant-relationship-product-list-data-import:"^0.1.3"](https://github.com/spryker/merchant-relationship-product-list-data-import/releases/tag/0.1.3) - [spryker/price-product-merchant-relationship-data-import:"^0.2.5"](https://github.com/spryker/price-product-merchant-relationship-data-import/releases/tag/0.2.5) ### Dynamic entity performance improvements - [spryker/dynamic-entity:^1.21.0](https://github.com/spryker/dynamic-entity/releases/tag/1.21.0) - [spryker/dynamic-entity-backend-api:^1.15.0](https://github.com/spryker/dynamic-entity-backend-api/releases/tag/1.15.0) - [spryker/stock:^8.15.0](https://github.com/spryker/stock/releases/tag/8.15.0) ### Cart page and checkout for large carts (100+ items) For comprehensive guidance on optimizing cart performance, see [Cart page performance configuration](https://docs.spryker.com/docs/pbc/all/cart-and-checkout/latest/cart-page-performance-configuration.html). - [spryker-shop/checkout-page:^3.41.0](https://github.com/spryker-shop/checkout-page/releases/tag/3.41.0) - [spryker-shop/session-customer-validation-page:^1.4.0](https://github.com/spryker-shop/session-customer-validation-page/releases/tag/1.4.0) ## Update strategy To effectively manage dependency updates: 1. **Monitor release notes**: Regularly check Spryker release notes for performance-related updates. 2. **Test in staging**: Always test module updates in a staging environment before production deployment. 3. **Prioritize performance modules**: Focus on modules that directly impact your application's performance bottlenecks. 4. **Use semantic versioning**: Understand the impact of major, minor, and patch updates. 5. **Batch related updates**: Group related module updates together for testing efficiency. ## Compatibility considerations When updating modules: - Check module compatibility with your current Spryker version - Review breaking changes in major version updates - Test all affected functionality after updates - Monitor application performance metrics before and after updates - Consider using Spryker's [Composer Dependency Manager](https://docs.spryker.com/docs/scos/dev/setup/managing-scos-dependencies-with-composer.html) Tue, 19 May 2026 08:42:59 +0000 https://docs.spryker.com/docs/dg/dev/guidelines/performance-guidelines/keeping-dependencies-updated.html https://docs.spryker.com/docs/dg/dev/guidelines/performance-guidelines/keeping-dependencies-updated.html