ProgramMatek’s PHP API Gateway, implemented with the Lumen framework, is a powerful tool that serves as a crucial component of microservices architectural patterns. Acting as a layer in front of all your services, the API gateway enables seamless communication between various components.
A Gateway to Seamless Communication
Vrata, meaning ‘gates’ in Russian, provides a simple and efficient API gateway solution for your PHP7 applications. With Lumen as its backbone, Vrata offers a lightweight and robust framework to handle your API traffic.
Requirements and Dependencies
To get started with Vrata, ensure that you have the following requirements and dependencies in place:
- PHP >= 7.0
- Lumen 5.3
- Guzzle 6
- Laravel Passport (with Lumen Passport)
- Memcached (for request throttling)
Running Vrata as a Docker Container
Running Vrata as a stateless Docker container offers the advantage of easy configuration using environment variables. By leveraging our publicly available Docker Hub image, you can effortlessly deploy Vrata without the need to manage any code deployment. Simply specify the desired environment variables as JSON-encoded settings.
Configuration Made Simple
With Vrata, we believe in the power of simplicity. The API gateway doesn’t require extensive code modifications. Most of the configuration can be done by setting environment variables. Vrata acts as a smart proxy, discovering microservices, making queries, and processing responses with minimal adjustments.
Terminology and Structure
Understanding the internal structure of a typical API gateway-microservices setup is essential. The API gateway, being stateless, can scale horizontally. This inherent scalability makes Vrata a versatile choice for handling your API traffic.
To ensure smooth operation of your API gateway, it’s recommended to set a few Lumen variables:
- CACHE_DRIVER: Set this to ‘memcached’ or another supported shared cache if you are running multiple instances of the API gateway. API rate limiting relies on cache.
- DB_DATABASE, DB_HOST, DB_PASSWORD, DB_USERNAME, DB_CONNECTION: Standard Lumen variables for your database credentials. These are necessary if you store user data in the database. Refer to Laravel/Lumen documentation for the list of supported databases.
- APP_KEY: Lumen application key
To enhance the functionality of your API gateway, certain gateway-specific variables need to be set. These include:
- PRIVATE_KEY: Place your private RSA key in this variable. You can generate the key using OpenSSL.
- PUBLIC_KEY: Put your public RSA key here. Extract the public key using OpenSSL.
- GATEWAY_SERVICES: A JSON array containing the microservices behind your API gateway.
- GATEWAY_ROUTES: A JSON array defining extra routes, including any aggregate routes.
- GATEWAY_GLOBAL: A JSON object that stores global settings for your API gateway.
For efficient logging, Vrata supports LogEntries out of the box. By setting a couple of environment variables, you can seamlessly send nginx and Lumen logs to LogEntries.
Features to Boost Your API Gateway
Vrata comes equipped with a range of powerful features that will take your API gateway to the next level:
- Built-in OAuth2 server for streamlined authentication of incoming requests.
- Aggregate queries to combine output from multiple APIs.
- Output restructuring to tailor the response to your specific needs.
- Aggregate Swagger documentation that combines Swagger docs from underlying services.
- Automatic mounting of routes based on Swagger JSON.
- Support for synchronous and asynchronous outgoing requests.
- DNS service discovery for easy management of microservices.
Easy Installation Options
Installing Vrata is a breeze. You can either clone the repository or use composer (Packagist) for a quick installation.
Simplifying API Endpoint Import
Vrata makes it straightforward to import Swagger-compliant endpoints. By defining the URL(s) of your Swagger documentation endpoints, you can seamlessly integrate them with your API gateway. Whether you have a Symfony2 microservice or any other compatible service, Vrata will automatically import the required endpoints during container start.
Seamless Authentication with OAuth2
Vrata comes bundled with Laravel Passport, a fully featured OAuth2 server. All API requests are authenticated using JSON Web Tokens (JWT), ensuring secure communication. Currently, Vrata supports local persistence (database) for token verification, but it’s easy to configure it with public keys for added flexibility.
Advanced Output Mutation
Vrata enables you to perform basic JSON output mutation using the output property of an action. With this feature, you can customize the response and structure it according to your requirements.
Unleash the Power of Performance
At ProgramMatek, we understand the importance of performance when it comes to your API gateway. That’s why we have chosen Lumen as the foundation for Vrata. With a lightning-fast bootstrapping time of just ~25ms on a basic machine, Vrata delivers excellent performance.
Let’s take a look at an example of an aggregate request to highlight Vrata’s performance capabilities. First, we’ll make separate requests to the underlying microservices:
The total time taken for all three requests is 91ms, including all web-server-related overhead. Now, let’s make a single aggregate request to the API gateway, which in turn will make the same three requests:
In this case, the total execution time for all three requests is just 56ms! The second and third requests were executed in parallel, thanks to Vrata’s asynchronous mode. We believe this is an impressive performance achievement.
Let’s dive into a couple of real-world examples to illustrate the versatility and power of Vrata.
Example 1: Single, Simple Microservice
Suppose you have a straightforward setup consisting of an API Gateway and a single microservice behind it. Here’s how you can configure Vrata for this scenario:
- Add the microservice to the GATEWAY_SERVICES environment variable, specifying the nickname and leaving the array empty to use default settings. Ensure that your microservice has a valid Swagger documentation endpoint.
- Define global settings in the GATEWAY_GLOBAL environment variable. Include the necessary details such as service hostname, request timeout, and Swagger documentation location.
php artisan gateway:parseto parse the Swagger documentation provided by the microservice. This command can also be executed automatically when starting a container if you use our Docker image.
- With the setup complete, your microservice’s routes will be available through the API gateway, accessible via the appropriate URLs. Don’t forget to set the PRIVATE_KEY and PUBLIC_KEY environment variables for authentication to work seamlessly.
Example 2: Multiple Microservices with Aggregate Requests
In this example, we’ll explore a more complex scenario involving multiple microservices and aggregate requests. Follow these steps to get started:
- Add the services to the GATEWAY_SERVICES environment variable. Vrata automatically detects the Swagger version for each service. Ensure that the DNS hostnames match the names specified.
- Define the GATEWAY_GLOBAL environment variable with the necessary global settings for your API gateway.
- To enable sophisticated requests such as aggregate requests, define the GATEWAY_ROUTES environment variable. This variable allows you to set up custom routes and specify the required actions.
- With these configurations in place, Vrata will import all routes from the specified microservices and start proxying requests to them.
Example 3: Multiple Microservices with Aggregate POST, PUT, and DELETE Requests
For scenarios that involve POST, PUT, or DELETE requests, Vrata provides powerful options for handling diverse requirements. You can use the origin tag in your JSON body to refer to the initial request’s data. Additionally, you can leverage the response from each action in subsequent actions, enabling you to construct powerful aggregate requests.
Vrata is released under the MIT License. Visit our website to learn more about how Vrata can enhance your API gateway.
The MIT License (MIT)
Copyright (c) 2017-2018 PoweredLocal
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.