Glue API installation and configuration

Last updated:
Edit on GitHub

Functionally, Spryker API can be split into 2 parts: API infrastructure (GLUE) and feature modules. The infrastructure provides the general functionality of the API layer, while each feature module implements a specific resource or resource relation.

To integrate GLUE API in your project, you need to:

1. Installing GLUE

GLUE infrastructure is shipped with the following modules:

MODULE DESCRIPTION
GlueApplication Provides API infrastructure for Spryker features.
GlueApplicationExtension Provides extension point/plugin interfaces for the Glue Application module.
AuthRestApi (optional) Provides API endpoints to obtain an authentication token to use for subsequent requests.

To install it, you need to do the following:

Note

Spryker Shop Suite contains GLUE out of the box. If your project has the latest Shop Suite master merged, you can proceed directly to step 2. Enable GLUE.

  1. Install the necessary modules using composer:

    composer update "spryker/*" "spryker-shop/*" --update-with-dependencies
composer require spryker/glue-application --update-with-dependencies

  2. Add a Front Controller for GLUE:

    • In the directory where your code is installed, locate a directory public and create a subdirectory Glue in it.
    • Create a file index.php in the Glue directory with the following content:
<?php

use Pyz\Glue\GlueApplication\Bootstrap\GlueBootstrap;
use Spryker\Shared\Config\Application\Environment;
use Spryker\Shared\ErrorHandler\ErrorHandlerEnvironment;

define('APPLICATION', 'GLUE');
defined('APPLICATION_ROOT_DIR') || define('APPLICATION_ROOT_DIR', realpath(__DIR__ . '/../..'));

require_once APPLICATION_ROOT_DIR . '/vendor/autoload.php';

Environment::initialize();

$errorHandlerEnvironment = new ErrorHandlerEnvironment();
$errorHandlerEnvironment->initialize();

$bootstrap = new GlueBootstrap();
$bootstrap
    ->boot()
    ->run();
  1. Create GLUE application bootstrap:
    • In the src/Pyz directory of your Spryker code installation, create a folder Glue, then create a subfolder GlueApplication/Bootstrap in it.
    • In the GlueApplication/Bootstrap folder, create file GlueBootstrap.php with the following content:
<?php

namespace Pyz\Glue\GlueApplication\Bootstrap;

use Spryker\Glue\GlueApplication\Bootstrap\AbstractGlueBootstrap;

class GlueBootstrap extends AbstractGlueBootstrap
{
}

  1. Create GLUE dependency provider:

    In the src/Pyz/GlueApplication directory of your Spryker code installation, create a file GlueApplicationDependencyProvider.php and add the following code:

<?php

namespace Pyz\Glue\GlueApplication;

use Spryker\Glue\EventDispatcher\Plugin\Application\EventDispatcherApplicationPlugin;
use Spryker\Glue\GlueApplication\GlueApplicationDependencyProvider as SprykerGlueApplicationDependencyProvider;
use Spryker\Glue\GlueApplication\Plugin\Application\GlueApplicationApplicationPlugin;
use Spryker\Glue\Router\Plugin\Application\RouterApplicationPlugin;
use Spryker\Glue\Session\Plugin\Application\SessionApplicationPlugin;

class GlueApplicationDependencyProvider extends SprykerGlueApplicationDependencyProvider
{
    /**
     * @return \Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\ResourceRoutePluginInterface[]
     */
    protected function getResourceRoutePlugins(): array
    {
        return [];
    }

    /**
     * @return \Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\ValidateRestRequestPluginInterface[]
     */
    protected function getValidateRestRequestPlugins(): array
    {
        return [];
    }

    /**
     * @return \Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\FormatResponseHeadersPluginInterface[]
     */
    protected function getFormatResponseHeadersPlugins(): array
    {
        return [];
    }

    /**
     * @return \Spryker\Glue\GlueApplicationExtension\Dependency\Plugin\ControllerBeforeActionPluginInterface[]
     */
    protected function getControllerBeforeActionPlugins(): array
    {
        return [];
    }

    /**
     * @return \Spryker\Shared\ApplicationExtension\Dependency\Plugin\ApplicationPluginInterface[]
     */
    protected function getApplicationPlugins(): array
    {
        return [
            new SessionApplicationPlugin(),
            new EventDispatcherApplicationPlugin(),
            new GlueApplicationApplicationPlugin(),
            new RouterApplicationPlugin(),
        ];
    }
}
  1. Add GLUE application constants to your environment.

Finally, you need to add GLUE application constants to your environment configuration file. The following is an example of the development environment:

use Spryker\Shared\GlueApplication\GlueApplicationConstants;
...
// ----------- Glue Application
$config[GlueApplicationConstants::GLUE_APPLICATION_DOMAIN] = '<your_glue_domain>';
$config[GlueApplicationConstants::GLUE_APPLICATION_REST_DEBUG] = false;

where <your_glue_domain> is the URL domain you want to use for GLUE. If you want to use the default domain of the Spryker shop, you can leave it empty.

Tip

If you want to enable GLUE application debugging, set the GLUE_APPLICATION_REST_DEBUG variable to true.

  1. Enable customer authentication via OAuth tokens (optional)

GLUE provides the possibility to authenticate customer users with the help of OAuth tokens. If you are going to use customer authentication, you will also need to perform the following additional steps:

  • Install the AuthRestApi and OauthCustomerConnector modules:
composer require spryker/auth-rest-api spryker/oauth-customer-connector --update-with-dependencies
  • Add OAuth plugins to the GLUE dependency provider. To do this, open file src/Pyz/GlueApplication/GlueApplicationDependencyProvider.php and make the following changes: Add use statements for the required OAuth plugins:
...
namespace Pyz\Glue\GlueApplication;

use Spryker\Glue\AuthRestApi\Plugin\AccessTokensResourceRoutePlugin;
use Spryker\Glue\AuthRestApi\Plugin\FormatAuthenticationErrorResponseHeadersPlugin;
use Spryker\Glue\AuthRestApi\Plugin\GlueApplication\AccessTokenRestRequestValidatorPlugin;
use Spryker\Glue\AuthRestApi\Plugin\GlueApplication\SimultaneousAuthenticationRestRequestValidatorPlugin;
use Spryker\Glue\AuthRestApi\Plugin\GlueApplication\TokenResourceRoutePlugin;
use Spryker\Glue\AuthRestApi\Plugin\RefreshTokensResourceRoutePlugin;
use Spryker\Glue\AuthRestApi\Plugin\RestUserFinderByAccessTokenPlugin.;..

Add OAuth resource plugins:

protected function getResourceRoutePlugins(): array
{
    return [
        new AccessTokensResourceRoutePlugin(),
        new RefreshTokensResourceRoutePlugin(),
	new TokenResourceRoutePlugin()
    ];
}

Add token validation plugins:

protected function getRestRequestValidatorPlugins(): array
{
    return [
        new AccessTokenRestRequestValidatorPlugin(),
	new SimultaneousAuthenticationRestRequestValidatorPlugin(),
    ];
}

Add error response plugin:

protected function getFormatResponseHeadersPlugins(): array
{
    return [
        new FormatAuthenticationErrorResponseHeadersPlugin(),
    ];
}

Add Oauth user finder plugin:

protected function getRestUserFinderPlugins(): array
{
    return [
        new RestUserFinderByAccessTokenPlugin(),
    ];
}
  • Add OAuth dependency provider. To do this, create file Pyz/Zed/Oauth/OauthDependencyProvider.php as follows:
<?php

namespace Pyz\Zed\Oauth;

use Spryker\Zed\Oauth\OauthDependencyProvider as SprykerOauthDependencyProvider;
use Spryker\Zed\OauthCustomerConnector\Communication\Plugin\Oauth\CustomerOauthScopeProviderPlugin;
use Spryker\Zed\OauthCustomerConnector\Communication\Plugin\Oauth\CustomerOauthUserProviderPlugin;

class OauthDependencyProvider extends SprykerOauthDependencyProvider
{
    /**
     * @return \Spryker\Zed\OauthExtension\Dependency\Plugin\OauthUserProviderPluginInterface[]
     */
    protected function getUserProviderPlugins(): array
    {
        return [
            new CustomerOauthUserProviderPlugin(),
        ];
    }

    /**
     * @return \Spryker\Zed\OauthExtension\Dependency\Plugin\OauthScopeProviderPluginInterface[]
     */
    protected function getScopeProviderPlugins(): array
    {
        return [
            new CustomerOauthScopeProviderPlugin(),
        ];
    }
}
  • Add OAuth public and private keys. For development purposes, you can use the keys supplied with Spryker Shop Suite. In production, you will need your own keys generated per the following instructions: Generating public and private keys. The keys need to be placed in the config/Zed directory of your code installation (in the Shop Suite, dev_only_private.key and dev_only_public.key are used).
  • Add OAuth constants to your environment configuration file. In the development environment, you can use the following:
use Spryker\Shared\Oauth\OauthConstants;
...
// ----------- OAUTH
$config[OauthConstants::PRIVATE_KEY_PATH] = 'file://' . APPLICATION_ROOT_DIR . '/config/Zed/dev_only_private.key';
$config[OauthConstants::PUBLIC_KEY_PATH] = 'file://' . APPLICATION_ROOT_DIR . '/config/Zed/dev_only_public.key';
$config[OauthConstants::ENCRYPTION_KEY] = 'lxZFUEsBCJ2Yb14IF2ygAHI5N4+ZAUXXaSeeJm6+twsUmIen';

// ----------- AuthRestApi
$config[OauthConstants::OAUTH_CLIENT_IDENTIFIER] = 'frontend';
$config[OauthConstants::OAUTH_CLIENT_SECRET] = 'abc123';

2. Enabling GLUE

To use GLUE in your project, configure an Nginx host to serve REST API requests:

1. Create Nginx VHOST configuration

sudo nano /etc/nginx/sites-enabled/DE_development_glue

In the nano console that opens, paste the following:

server {
    # Listener for production/staging - requires external LoadBalancer directing traffic to this port
    listen 10001;

    # Listener for testing/development - one host only, doesn't require external LoadBalancer
    listen 80;

    server_name ~^glue\\.de\\..+\\.local$;

    keepalive_timeout 0;
    access_log  /data/logs/development/glue-access.log extended;

    root /data/shop/development/current/public/Glue;

    set $application_env development;
    set $application_store DE;
    include "spryker/zed.conf";
}

Restart Nginx

sudo /etc/init.d/nginx restart

2. Change the machine hosts configuration

sudo nano /etc/hosts

Add the following line to the end of the file:

ip glue.de.project-name.local

After performing this change, you should be able to access https://glue.mysprykershop.com with a 404 error and JSON response indicating that the resource is not found.

If you are running your project in the Spryker VM, you also need to make changes to the Vagrant file of the virtual machine. To do so:

  1. Open the file ~/.vagrant.d/boxes/devvm[version]/0/virtualbox/include/_Vagrantfile, where [version] is the VM version. On Windows, you can find the .vagrant.d folder in your user profile folder.

  2. Find the following line:

HOSTS.push [ "www#{host_suffix}.#{store}.#{domain}", "zed#{host_suffix}.#{store}.#{domain}",]
  1. Change it as follows:
HOSTS.push [ "www#{host_suffix}.#{store}.#{domain}", "glue#{host_suffix}.#{store}.#{domain}", "zed#{host_suffix}.#{store}.#{domain}",]

3. Set correct OAuth key permissions

If you are using the OAuth module for user authentication, change permissions for the OAuth keys:

chmod 660 config/Zed/dev_only_public.key
chmod 660 config/Zed/dev_only_private.key

Integrate REST API resources

After installing and enabling GLUE, you can integrate various REST API resources with it. It is not required to integrate all modules for REST API to work. You can integrate only the modules you need.