Create and change Glue API conventions

Last updated:
Edit on GitHub

The Glue API Convention feature lets you change the way your API accepts or returns data.

The following diagram demonstrates the Glue request flow that highlights where the convention can affect the execution.

A convention has a say in every step of the request flow:

  • Resolving the convention happens first. Any data in GlueRequestTransfer can affect the resolution of the convention. For example, projects can pull attributes from a certain location in the content.
  • At the request building step, you can extract and pre-format the data from the raw request data.
  • A convention can add validation steps that are necessary for its flow, both before and after the routing.
  • Formatting response can be used to wrap the response attributes in the convention-determined wrapper.

Create a new convention

To crete a new convention, implement ConventionPluginInterface:

<?php

namespace Pyz\Glue\GlueJsonApiConvention\Plugin\GlueApplication;

use Generated\Shared\Transfer\GlueRequestTransfer;
use Pyz\Glue\CustomConventionExtension\Dependency\Plugin\CustomResourceInterface;
use Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\ConventionPluginInterface;
use Spryker\Glue\Kernel\AbstractPlugin;

class CustomConventionPlugin extends AbstractPlugin implements ConventionPluginInterface
{
    /**
     * {@inheritDoc}
     *
     * @api
     *
     * @param \Generated\Shared\Transfer\GlueRequestTransfer $glueRequestTransfer
     *
     * @return bool
     */
    public function isApplicable(GlueRequestTransfer $glueRequestTransfer): bool
    {
        // Check any info in the GlueRequestTransfer, like headers.

        return true;
    }

    /**
     * {@inheritDoc}
     *
     * @api
     *
     * @return string
     */
    public function getName(): string
    {
        return 'CUSTOM_CONVENTION';
    }

    /**
     * {@inheritDoc}
     *
     * @api
     *
     * @return string
     */
    public function getResourceType(): string
    {
        // This interface must be implemented by resources that follow this convention.

        return CustomResourceInterface::class;
    }

    /**
     * {@inheritDoc}
     *
     * @api
     *
     * @return array<\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestBuilderPluginInterface>
     */
    public function provideRequestBuilderPlugins(): array
    {
        return $this->getFactory()->getRequestBuilderPlugins();
    }

    /**
     * {@inheritDoc}
     *
     * @api
     *
     * @return array<\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestValidatorPluginInterface>
     */
    public function provideRequestValidatorPlugins(): array
    {
        return $this->getFactory()->getRequestValidatorPlugins();
    }

    /**
     * {@inheritDoc}
     *
     * @api
     *
     * @return array<\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\RequestAfterRoutingValidatorPluginInterface>
     */
    public function provideRequestAfterRoutingValidatorPlugins(): array
    {
        return $this->getFactory()->getRequestAfterRoutingValidatorPlugins();
    }

    /**
     * {@inheritDoc}
     *
     * @api
     *
     * @return array<\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\ResponseFormatterPluginInterface>
     */
    public function provideResponseFormatterPlugins(): array
    {
        return $this->getFactory()->getResponseFormatterPlugins();
    }
}

Use a convention

To use the newly created convention, you must add it to the GlueApplicationDependencyProvider::getConventionPlugins().

<?php

namespace namespace Pyz\Glue\GlueApplication;

use Pyz\Glue\GlueJsonApiConvention\Plugin\GlueApplication\CustomConventionPlugin;
use Spryker\Glue\GlueApplication\GlueApplicationDependencyProvider as SprykerGlueApplicationDependencyProvider;

class GlueApplicationDependencyProvider extends SprykerGlueApplicationDependencyProvider
{
    /**
     * @return array<\Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\ConventionPluginInterface>
     */
    protected function getConventionPlugins(): array
    {
        return [
            new CustomConventionPlugin(),
        ];
    }
}

If no convention has been defined, endpoints will work with default (no convention) behavior. In this case, the resource should implement Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\ResourceInterface.