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.

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:"^0.1.0" --update-with-dependencies
Module placeholder

The exact module versions will be provided in the final documentation. The above serves as a placeholder for the module list.

2. Register bundles

Register the required bundles in your application’s bundle configuration files for each application layer where you want to enable API Platform.

For Glue application

config/Glue/bundles.php

<?php

declare(strict_types = 1);

use ApiPlatform\Symfony\Bundle\ApiPlatformBundle;
use Nelmio\CorsBundle\NelmioCorsBundle;
use Spryker\ApiPlatform\SprykerApiPlatformBundle;
use Symfony\Bundle\FrameworkBundle\FrameworkBundle;
use Symfony\Bundle\TwigBundle\TwigBundle;

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

For GlueStorefront application

config/GlueStorefront/bundles.php

<?php

declare(strict_types = 1);

use ApiPlatform\Symfony\Bundle\ApiPlatformBundle;
use Nelmio\CorsBundle\NelmioCorsBundle;
use Spryker\ApiPlatform\SprykerApiPlatformBundle;
use Symfony\Bundle\FrameworkBundle\FrameworkBundle;
use Symfony\Bundle\TwigBundle\TwigBundle;

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

For GlueBackend application

config/GlueBackend/bundles.php

<?php

declare(strict_types = 1);

use ApiPlatform\Symfony\Bundle\ApiPlatformBundle;
use Nelmio\CorsBundle\NelmioCorsBundle;
use Spryker\ApiPlatform\SprykerApiPlatformBundle;
use Symfony\Bundle\FrameworkBundle\FrameworkBundle;
use Symfony\Bundle\TwigBundle\TwigBundle;

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

3. Configure API Platform

Create configuration files for the API Platform in each application layer where you want to enable the API-Platform.

Configure for Glue

config/Glue/packages/spryker_api_platform.php

<?php

declare(strict_types=1);

use Symfony\Config\SprykerApiPlatformConfig;

return static function (SprykerApiPlatformConfig $sprykerApiPlatform): void {
    $sprykerApiPlatform->apiTypes(['storefront']);
};

Configure for GlueStorefront

config/GlueStorefront/packages/spryker_api_platform.php

<?php

declare(strict_types=1);

use Symfony\Config\SprykerApiPlatformConfig;

return static function (SprykerApiPlatformConfig $sprykerApiPlatform): void {
    $sprykerApiPlatform->apiTypes(['storefront']);
};

Configure for GlueBackend

config/GlueBackend/packages/spryker_api_platform.php

<?php

declare(strict_types=1);

use Symfony\Config\SprykerApiPlatformConfig;

return static function (SprykerApiPlatformConfig $sprykerApiPlatform): void {
    $sprykerApiPlatform->apiTypes(['backend']);
};

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 schema files:

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

# Generate resources for all configured API types in GlueStorefront
docker/sdk cli GLUE_APPLICATION=GLUE_STOREFRONT glue api:generate

# Generate resources for all configured API types in GlueBackend
docker/sdk cli GLUE_APPLICATION=GLUE_BACKEND glue api:generate

# Generate resources for a specific API type in Glue (others can follow the env var examples above)
docker/sdk cli glue api:generate storefront
docker/sdk cli glue api:generate backend

# Dry run (see what would be generated)
docker/sdk cli glue api:generate --dry-run

# Validate schemas only
docker/sdk cli glue api:generate --validate-only

The generated resources will be created in src/Generated/Api/{ApiType}/ directory.

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 api_platform.enable_docs setting in your configuration files.

Next steps