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 directory public and create subdirectory Glue in it.
    • Create 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 folder Glue, then create 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 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.
6. 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 closes for the required OAuth plugins:
...
namespace Pyz\Glue\GlueApplication;
 
use Spryker\Glue\AuthRestApi\Plugin\AccessTokensResourceRoutePlugin;
use Spryker\Glue\AuthRestApi\Plugin\AccessTokenValidatorPlugin;
use Spryker\Glue\AuthRestApi\Plugin\FormatAuthenticationErrorResponseHeadersPlugin;
use Spryker\Glue\AuthRestApi\Plugin\RefreshTokensResourceRoutePlugin;...

Add OAuth resource plugins:

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

Add token validation plugin:

protected function getValidateRestRequestPlugins(): array
{
    return [
        new AccessTokenValidatorPlugin(),
    ];
}

Add error response plugin:

protected function getFormatResponseHeadersPlugins(): array
{
    return [
        new FormatAuthenticationErrorResponseHeadersPlugin(),
    ];
}
  • 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[OauthCustomerConnectorConstants::OAUTH_CLIENT_IDENTIFIER] = 'frontend';
$config[OauthCustomerConnectorConstants::OAUTH_CLIENT_SECRET] = 'abc123';

2. Enabling GLUE

To be able to use GLUE in your project, you need to configure a 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 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 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.

Login API

Provides the possibility to authenticate customer users. The API is provided by the following module: |Module|Description| |—|—| |AuthRestApi|Provides API endpoints to obtain an authentication token to use for subsequent requests.| Installation steps: see 1.6. Enable customer authentication via OAuth tokens.

Registration API

Provides the possibility to register new customers. The API is provided by the following module: |Module|Description| |—|—| |CustomersRestApi|Provides API endpoints to manage customers.|

Installation steps:

  1. Install the module using Composer:
composer require spryker/customers-rest-api --update-with-dependencies
  1. Add a resource route plugin to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php::getResourceRoutePlugins():
protected function getResourceRoutePlugins(): array
    {
        return [
            ...
            new CustomersResourceRoutePlugin(),
        ];
    }
  1. Run the following command:
console transfer:generate

Products API

Provides endpoints to retrieve information about products. The API is provided by the following modules:

|Module |DescriptionEndpoints Provided| |—|—|—| |ProductsRestApi|Provides REST access to products.|/abstract-products
/concrete-products| |ProductAvailabilitiesRestApi|Provides API endpoints to get abstract and concrete product availability.|/abstract-products/{{sku}}/abstract-product-availabilities
/concrete-products/{{sku}}/concrete-product-availabilities| |ProductsProductAvailabilitiesResourceRelationship|Provides relationship between products (abstract and concrete) and product availabilities resources.|-| |ProductPricesRestApi|Provides API endpoints to retrieve abstract and concrete product prices.|/abstract-products/{{sku}}/abstract-product-prices
/concrete-products/{{sku}}/concrete-product-prices| |ProductsProductPricesResourceRelationship|Provides relationship between products (abstract and concrete) and product prices resources.|-| |ProductTaxSetsRestApi|Provides API endpoints to retrieve product tax sets.|/abstract-products/{{SKU}}/product-tax-sets| |ProductsProductTaxSetsResourceRelationship|Provides relationship between abstract products and tax sets resources.|-| |ProductImageSetsRestApi|Provides API endpoints to retrieve product image sets.|/abstract-products/{{sku}}/abstract-product-image-sets
/concrete-products/{{sku}}/concrete-product-image-sets|

You can chose whether to install all modules of the API to retrieve full Products API functionality, or install any of the modules individually to get only the endpoints you need.

Relationship Modules
Relationship modules provide relationship between products and related entities (e.g. between products and the tax sets available for them). This means that, when a module is installed, a request for information on a certain product will also return information on the related resource by default. If the module is not installed, you need to query the related resource explicitly. In other words, if the `ProductsProductTaxSetsResourceRelationship` module is installed, a query for an abstract product will also return full data of the tax sets related to them. If it is not installed, you will need to query the `/abstract-products/{{SKU}}/product-tax-sets` explicitly.

Installation steps: ProductsRestApi:

  1. Install the module using Composer:
composer require spryker/products-rest-api --update-with-dependencies
  1. Add resource route plugins to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php::getResourceRoutePlugins():
protected function getResourceRoutePlugins(): array
    {
        return [
            ...
            new AbstractProductsResourceRoutePlugin(),
            new ConcreteProductsResourceRoutePlugin(),
        ];
    }
  1. Run the following command:
console transfer:generate

ProductAvailabilitiesRestApi:

  1. Install the module using Composer:
composer require spryker/product-availabilities-rest-api --update-with-dependencies
  1. Add resource route plugins to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php::getResourceRoutePlugins():
protected function getResourceRoutePlugins(): array
    {
        return [
            ...
            new AbstractProductAvailabilitiesRoutePlugin(), // Abstract product avaialbilities
            new ConcreteProductAvailabilitiesRoutePlugin(), // Concrete product avaialbilities
        ];
    }
  1. Run the following command:
console transfer:generate

ProductsProductAvailabilitiesResourceRelationship:

  1. Install the module using Composer:
composer require spryker/products-product-availabilities-resource-relationship --update-with-dependencies
  1. Add resource route plugins to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php::getResourceRelationshipPlugins():
protected function getResourceRelationshipPlugins(
        ResourceRelationshipCollectionInterface $resourceRelationshipCollection
    ): ResourceRelationshipCollectionInterface
    {
        ...
        $resourceRelationshipCollection->addRelationship(
            ProductsRestApiConfig::RESOURCE_ABSTRACT_PRODUCTS,
            new ProductsProductAvailabilitiesResourceRelationshipPlugin()
        );
   
        return $resourceRelationshipCollection;
    }

Stores API

Provides API endpoints to retrieve current store configuration. The API is provided by the following module: |Modules|Description| |—|—| |StoresRestApi|Provides REST API endpoints to stores.| Installation steps:

  1. Install the module using Composer:
composer require spryker/stores-rest-api --update-with-dependencies
  1. Add resource route plugin to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php::getResourceRoutePlugins():
protected function getResourceRoutePlugins(): array
    {
        return [
            ...
            new StoresResourceRoutePlugin(),
        ];
    }
  1. Run the following command:
console transfer:generate

Search API

Provides the possibility to perform searches and retrieve search suggestions via the REST API. The API is provided by the following module: |Modules|Description| |—|—| |CatalogSearchRestApi|Provides REST API endpoints to search products and search suggestions.|

Installation steps:

  1. Install the module using Composer:
composer require spryker/catalog-search-rest-api --update-with-dependencies
  1. Add plugins for catalog search and search suggestions to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php::getResourceRoutePlugins():
protected function getResourceRoutePlugins(): array
    {
        return [
            ...
            new SearchResourceRoutePlugin(),
            new SuggestionsResourceRoutePlugin(),
        ];
    }
  1. Run the following command:
console transfer:generate
  1. If your store also provides the Products API, you need to add relationship between the Search and Products APIs:
composer require spryker/catalog-search-products-resource-relationship --update-with-dependencies

After this, add the products resource relation plugins to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php::getResourceRelationshipPlugins():

protected function getResourceRelationshipPlugins(
        ResourceRelationshipCollectionInterface $resourceRelationshipCollection
    ): ResourceRelationshipCollectionInterface {
        $resourceRelationshipCollection->addRelationship(
            CatalogSearchRestApiConfig::RESOURCE_CATALOG_SEARCH,
            new CatalogSearchAbstractProductsResourceRelationshipPlugin()
        );
        $resourceRelationshipCollection->addRelationship(
            CatalogSearchRestApiConfig::RESOURCE_CATALOG_SEARCH_SUGGESTIONS,
            new CatalogSearchSuggestionsAbstractProductsResourceRelationshipPlugin()
        );
  
        return $resourceRelationshipCollection;
    }

Category API

Provides the possibility to retrieve the category tree and category nodes. The API is provided by the following module: |Modules|Description| |—|—| |CategoriesRestApi|Provides REST API endpoints to fetch category tree and category nodes by node ID.| Installation steps:

  1. Install the module using Composer:
composer require spryker/categories-rest-api --update-with-dependencies
  1. Add plugins for category-trees and category-nodes resources to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php::getResourceRoutePlugins():
protected function getResourceRoutePlugins(): array
    {
        return [
            ...
            new CategoriesResourceRoutePlugin(),
            new CategoryResourceRoutePlugin(),
        ];
    }
  1. Run the following command:
console transfer:generate

Carts API

Provides the possibility to manage customer carts and cart items. The API is provided by the following module: |Modules|Description| |—|—| |CartsRestApi|Provides REST API endpoints to create, get, delete carts for registered customers (using persistent storage), as well as manage cart items.| Installation steps:

  1. Install the module using Composer:
composer require spryker/cart-items-products-relationship:"^1.0.0" spryker/carts-rest-api:"^1.0.0" --update-with-dependencies
  1. Add carts and cart items resource route plugin to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php::getResourceRoutePlugins():
protected function getResourceRoutePlugins(): array
    {
        return [
            ...
            new CartsResourceRoutePlugin(),
            new CartItemsResourceRoutePlugin(),
        ];
    }
  1. Run Propel install to add the UUID functionality:
console propel:install
  1. Generate Propel transfer objects:
console transfer:generate
  1. Run the following command to update all existing customers carts with a UUID value.
console quote:uuid:generate

Product Labels API

Provides the possibility to retrieve product labels. The API is provided by the following module: |Modules|Description|Endpoints Provided| |—|—|—| |ProductLabelsRestApi|Provides REST API endpoints for product labels.|/product-labels/{{label-id}}|

Installation steps:

  1. Install the module using Composer:
composer require spryker/product-labels-rest-api --update-with-dependencies
  1. Add plugin declaration to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php:getResourceRoutePlugins():
protected function getResourceRoutePlugins(): array
    {
        return [
            ...,
            new ProductLabelsResourceRoutePlugin(),
            ...,
  1. Run the following command:
console transfer:generate

Retrieving Labels for Products Out of the box, the API provides the possibility to access labels by their ID. If you also want to retrieve labels assigned to a product together with product information, you need to install an additional relationship module:

  1. Install the module using Composer:
composer require spryker/product-labels-rest-api --update-with-dependencies
  1. Add the products resource relation plugin to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php::getResourceRelationshipPlugins():
protected function getResourceRelationshipPlugins(
        ResourceRelationshipCollectionInterface $resourceRelationshipCollection
    ): ResourceRelationshipCollectionInterface {
        $resourceRelationshipCollection->addRelationship(
            ProductsRestApiConfig::RESOURCE_ABSTRACT_PRODUCTS,
            new ProductLabelsRelationshipByResourceIdPlugin()
        );
  
        return $resourceRelationshipCollection;
    }
  1. Run the following command:
console transfer:generate

Checkout API

Provides the possibility to place orders and retrieve checkout information. The API is provided by the following module: |Modules|Description|Endpoints Provided| |—|—|—| |CheckoutRestApi|||  Installation steps: Placing an Order

  1. Install the module using Composer:
composer require spryker/product-labels-rest-api --update-with-dependencies
  1. Add plugin declaration to src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php:getResourceRoutePlugins():
protected function getResourceRoutePlugins(): array
    {
        return [
            ...,
            new CheckoutResourcePlugin(),
            ...,
  1. Add relationship to the order to src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php:getResourceRelationshipPlugins():
protected function getResourceRelationshipPlugins(
         ResourceRelationshipCollectionInterface $resourceRelationshipCollection
     ): ResourceRelationshipCollectionInterface {
        ...
        $resourceRelationshipCollection->addRelationship(
            CheckoutRestApiConfig::RESOURCE_CHECKOUT,
            new OrderRelationshipByOrderReferencePlugin()
        );
        ...

Retrieving Checkout Data

  1. Install the module using Composer:
composer require spryker/product-labels-rest-api --update-with-dependencies
  1. Add plugin declaration to src/Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php:getResourceRoutePlugins():
protected function getResourceRoutePlugins(): array
    {
        return [
            ...,
            new CheckoutDataResourcePlugin(),
            ...,

Customers API

Provides the possibility to retrieve product labels. The API is provided by the following module: |Modules|Description|Endpoints Provided| |—|—|—| |CustomersRestApi|Provides endpoints that allow you to manage customers.|/customers
/customers/{{customer_id}}
/customers/{{customer_id}}/addresses
/customers/{{customer_id}}/addresses/{{address_id}}| Installation steps:

  1. Install the module using Composer:
composer require spryker/customers-rest-api --update-with-dependencies
composer require spryker/wishlists-rest-api --update-with-dependencies
  1. Add plugin declaration to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php::getResourceRoutePlugins():
protected function getResourceRoutePlugins(): array
{
    return [
        ...
        new CustomersResourceRoutePlugin(),
        new AddressesResourceRoutePlugin(),
    ];
}
  1. Add CustomersToAddressesRelationshipPlugin and WishlistRelationshipByResourceIdPlugin to /Pyz/Glue/GlueApplication/GlueApplicationDependencyProvider.php::getResourceRelationshipPlugins():
protected function getResourceRelationshipPlugins(
    ResourceRelationshipCollectionInterface $resourceRelationshipCollection
): ResourceRelationshipCollectionInterface {
    $resourceRelationshipCollection->addRelationship(
        CustomersRestApiConfig::RESOURCE_CUSTOMERS,
        new CustomersToAddressesRelationshipPlugin()
    );
    $resourceRelationshipCollection->addRelationship(
        CustomersRestApiConfig::RESOURCE_CUSTOMERS,
        new WishlistRelationshipByResourceIdPlugin()
    );
    return $resourceRelationshipCollection;
}
  1. Run the following command:
console transfer:generate
console propel:install
console customer-addresses:uuid:generate