Glue API installation and configuration
Edit on GitHubFunctionally, 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:
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.
-
Install the necessary modules using composer:
composer update "spryker/*" "spryker-shop/*" --update-with-dependencies composer require spryker/glue-application --update-with-dependencies
-
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();
- Create GLUE application bootstrap:
- In the
src/Pyz
directory of your Spryker code installation, create a folder Glue, then create a subfolderGlueApplication/Bootstrap
in it. - In the GlueApplication/Bootstrap folder, create file GlueBootstrap.php with the following content:
- In the
<?php
namespace Pyz\Glue\GlueApplication\Bootstrap;
use Spryker\Glue\GlueApplication\Bootstrap\AbstractGlueBootstrap;
class GlueBootstrap extends AbstractGlueBootstrap
{
}
-
Create GLUE dependency provider:
In the
src/Pyz/GlueApplication
directory of your Spryker code installation, create a fileGlueApplicationDependencyProvider.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(),
];
}
}
- 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.
If you want to enable GLUE application debugging, set the GLUE_APPLICATION_REST_DEBUG
variable to true.
- 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
andOauthCustomerConnector
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
anddev_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:
-
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. -
Find the following line:
HOSTS.push [ "www#{host_suffix}.#{store}.#{domain}", "zed#{host_suffix}.#{store}.#{domain}",]
- 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.
Thank you!
For submitting the form