How to integrate API Platform

Last updated:
Edit on GitHub

This document describes how to integrate API Platform into your Spryker application to enable schema-based API resource generation.

If you’re migrating an existing Spryker shop from the Glue REST stack, read the API Platform migration overview first. This integration guide is one step inside that larger flow.

Prerequisites

Before integrating API Platform, ensure you have:

1. Install the required modules

To integrate API Platform, install the following modules:

composer require spryker/api-platform:"^1.0.0" --update-with-dependencies
Target versions

For the list of currently migrated modules and their status, see the Glue API to API Platform migration status page. Update your spryker/*-rest-api modules to a version that ships the endpoints you migrate.

2. Register bundles

Register the required bundles in each application’s bundle file — config/Glue/bundles.php, config/GlueStorefront/bundles.php, and config/GlueBackend/bundles.php are identical:

<?php

declare(strict_types = 1);

use ApiPlatform\Symfony\Bundle\ApiPlatformBundle;
use Spryker\ApiPlatform\SprykerApiPlatformBundle;
use Symfony\Bundle\FrameworkBundle\FrameworkBundle;
use Symfony\Bundle\SecurityBundle\SecurityBundle;
use Symfony\Bundle\TwigBundle\TwigBundle;

return [
    FrameworkBundle::class => ['all' => true],
    SecurityBundle::class => ['all' => true],
    TwigBundle::class => ['all' => true],
    ApiPlatformBundle::class => ['all' => true],
    SprykerApiPlatformBundle::class => ['all' => true],
];
SecurityBundle

The SecurityBundle enables authentication and authorization for API Platform resources using Bearer token (JWT) validation and security expressions. For detailed setup including firewall configuration, see How to integrate API Platform Security.

3. Configure API Platform

Create a spryker_api_platform.php and an api_platform.php file in each application layer where you enable API Platform — config/Glue/packages/, config/GlueStorefront/packages/, and config/GlueBackend/packages/. At minimum, spryker_api_platform.php must set the application’s apiTypes() — ['storefront'] for the Glue and GlueStorefront applications, ['backend'] for the GlueBackend application.

For the full reference of both configuration files, every available setting, and links to the released demo-shop configurations, see API Platform Configuration.

4. Update Router Configuration

Update the router dependency provider for each application where you want to enable API Platform routes.

For Glue application

src/Pyz/Glue/Router/RouterDependencyProvider.php

<?php

declare(strict_types = 1);

namespace Pyz\Glue\Router;

use Spryker\Glue\Router\Plugin\Router\SymfonyFrameworkRouterPlugin;
use Spryker\Glue\GlueApplication\Plugin\Rest\GlueRouterPlugin;
use Spryker\Glue\Router\RouterDependencyProvider as SprykerRouterDependencyProvider;

class RouterDependencyProvider extends SprykerRouterDependencyProvider
{
    /**
     * @return array<\Spryker\Glue\RouterExtension\Dependency\Plugin\RouterPluginInterface>
     */
    protected function getRouterPlugins(): array
    {
        return [
            new GlueRouterPlugin(), // Existing Glue API router
            new SymfonyFrameworkRouterPlugin(), // Add this for API Platform routes
        ];
    }
}
Router order matters

The order of router plugins matters. The SymfonyFrameworkRouterPlugin must be added after existing router plugins to ensure the correct routing priority. The GlueRouterPlugin should remain the first in the list to handle existing and not yet migrated Glue API endpoints.

When migrating existing Glue API endpoints to API Platform, you need to remove endpoints from the GlueRouterPlugin so that the SymfonyFrameworkRouterPlugin is used to resolve the route. To remove routes from the GlueRouterPlugin update the corresponding GlueApplicationDependencyProvider, GlueBackendApiApplicationDependencyProvider, or GlueStorefrontApiApplicationDependencyProvider and remove the resource route plugin for the route you currently migrate.

5. Generate API resources

After configuration, generate your API resources from the schema files:

# Generate resources for all configured API types
docker/sdk cli glue api:generate

Target a specific application by prefixing with GLUE_APPLICATION=GLUE_STOREFRONT or GLUE_APPLICATION=GLUE_BACKEND. For the full set of generation and debug commands (single API type, --dry-run, --validate-only, schema inspection), see Resource generation in the architecture guide.

The generated resources are created in src/Generated/Api/{ApiType}/.

6. Install assets for the API Platform documentation interface

Install the necessary assets for API Platform to function correctly:

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
Required step

The assets:install command is required to copy the necessary assets (CSS, JavaScript, images) for the API Platform documentation interface. Without this step, the API documentation UI will not display correctly.

7. Clear caches

After generation and asset installation, clear application caches:

# Clear all caches
console cache:clear

# Build Symfony container cache
console container:build

Verification

To verify your integration:

  1. Debug available resources:

    # List all API resources
docker/sdk cli glue  api:debug --list

# Inspect specific resource
docker/sdk cli glue  api:debug access-tokens --api-type=storefront

  2. Access API documentation:

    • Glue: https://glue.your-domain/
    • GlueStorefront: https://glue-storefront.your-domain/
    • GlueBackend: https://glue-backend.your-domain/

    The interactive OpenAPI documentation interface will be displayed at the root URL of each application.

    Depending on the environment of the application (development or production), the documentation interface may be enabled or disabled by default. Currently, it is only enabled in development (docker.dev) environments.

    You can enable/disable this interface by configuring the settings in your api_platform.php configuration files.

Next steps