Troubleshooting API Platform

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 api:generate completes but no resources are created.

Possible causes:

1. Schema file location is incorrect

   ❌ src/Pyz/Glue/Customer/api/customers.yml
   ✅ src/Pyz/Glue/Customer/resources/api/backend/customers.yml
   

2. API type not configured

   Check config/{APPLICATION}/packages/spryker_api_platform.php:

   $containerConfigurator->extension('spryker_api_platform', [
       'api_types' => [
           'backend',  // Must match directory name
       ],
   ]);
   

3. Bundle not registered

   Verify config/{APPLICATION}/bundles.php includes:

   SprykerApiPlatformBundle::class => ['all' => true],
   

Solution:

# Debug to see what's being discovered
docker/sdk cli glue  api:debug --list

# Check schema validation
docker/sdk cli glue  api:generate --validate-only

# Force regeneration
docker/sdk cli glue  api:generate --force

Schema validation errors

Symptom: Generation fails with schema validation errors.

Common errors:

# Error: Invalid operation type
❌ operations:
    - type: CREATE

✅ operations:
    - type: Post

# Error: Invalid property type
❌ type: int
✅ type: integer

# Error: Missing resource name
❌ resource:
    shortName: Customer

✅ resource:
    name: Customers
    shortName: Customer

Solution:

1. Check schema against examples in documentation

2. Use --validate-only flag for detailed validation:

   docker/sdk cli glue  api:generate --validate-only
   

3. Inspect merged schema:

   docker/sdk cli glue  api:debug resource-name --show-merged
   

Runtime issues

Provider/Processor not found

Symptom:

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:

   namespace Pyz\Glue\Customer\Api\Backend\Provider;
   
   class CustomerBackendProvider implements ProviderInterface
   

2. Ensure services are auto-discovered in ApplicationServices.php:

   $services->load('Pyz\\Glue\\', '../../../src/Pyz/Glue/');
   

3. Check class name in the resource schema file of the module matches exactly:

   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:

   ✅ resources/api/backend/customers.validation.yml
   

2. Match operation names to HTTP methods:

   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:

   #[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

docker/sdk cli glue assets:install public/Glue/assets  --symlink

For GlueStorefront

docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue assets:install public/GlueStorefront/assets/  --symlink

For GlueBackend

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/

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:

   // RouterDependencyProvider
   protected function getRouterPlugins(): array
   {
       return [
           new GlueRouterPlugin(),
           new SymfonyFrameworkRouterPlugin(), // Must be present
       ];
   }
   

2. Check API documentation for correct URLs:

   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:

   ❌ /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:

   resource:
     paginationEnabled: true
     paginationItemsPerPage: 10
   

2. Return PaginatorInterface from provider:

   use ApiPlatform\State\Pagination\TraversablePaginator;
   
   return new TraversablePaginator(
       new \ArrayObject($results),
       $currentPage,
       $itemsPerPage,
       $totalItems
   );
   

3. Use pagination query parameters:

   GET /customers?page=2&itemsPerPage=20
   

Dependency Injection issues

Services not autowired

Symptom:

Cannot autowire service "CustomerBackendProvider": argument "$customerFacade"
references class "CustomerFacadeInterface" but no such service exists.

Solution:

1. Register facade in the respective applications ApplicationServices.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:

   public function __construct(
       private CustomerFacadeInterface $customerFacade,  // ✅ Interface
   ) {}
   

Performance issues

Slow API responses

Symptom: API endpoints respond slowly.

Solution:

1. Enable Symfony cache:

   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:

docker/sdk cli glue  api:debug customers --api-type=backend --show-sources

Output:

Source Files (priority order):
  ✓ vendor/spryker/customer/resources/api/backend/customers.yml (CORE)
  ✓ src/SprykerFeature/CRM/resources/api/backend/customers.yml (FEATURE)
  ✓ src/Pyz/Glue/Customer/resources/api/backend/customers.yml (PROJECT)

Inspecting generated code

View the generated resource class:

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:

docker/sdk cli glue  api:generate --dry-run

Getting help

If you encounter issues not covered here:

1. Check logs:

   tail -f var/log/application.log
   tail -f var/log/exception.log
   

2. Enable debug mode:

   // config/{APPLICATION}/packages/spryker_api_platform.php
   $containerConfigurator->extension('spryker_api_platform', [
       'debug' => true,
   ]);
   

3. Validate environment:

   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:

Next steps

• API Platform - Overview and concepts
• How to integrate API Platform - Setup guide
• API Platform Enablement - Creating resources
• Schemas and Resource Generation - Schema reference