IBM API Connect Microgateway framework, built on Node.js & Nginx
This is fork with datastore cache for http-responses. To enable it you must set env var DATASTORE_USE_LOCAL_CACHE=true.
The Microgateway is an developer-focused, extensible gateway framework written in Node.js for enforcing access to Microservices & APIs - https://developer.ibm.com/apiconnect/. It supports the following core features:
The role of a Gateway in an API architecture is to protect, enrich and control access to API services. These sets of capabilities are often related to security and rate limiting, but it also includes the ability to do deeper message inspection. For example, you may want to insure that the message received is properly formed JSON, XML, or data following your own specific format. In addition, the Gateway can modify the payload or transform it to meet old or new interfaces for the API backend. Finally, the Gateway can invoke multiple services and aggregate responses from multiple API backends.
The Microgateway is the foundation for all of those things. It is optimized to perform security, rate limiting, and much more complex packet processing through a highly flexible flow-engine.
The flow-engine is a processing unit that allows you to define a sequence of processing policies or tasks that get applied to the transaction as it passes through the Gateway for a specific API. These policies may be organized in a linear fashion, executing in sequential order. Or, they may have conditional logic deciding which set of policies will execute depending on variables that are part of the API flow.
The Microgateway currently contains the following policies that run implicitly based on swagger definitions:
The Microgateway currently contains the following polices that are available to the Assembly extension to the swagger definition:
GET
, HEAD
, POST
, PUT
, PATCH
, DELETE
, and OPTIONS
.The API Designer toolkit provides a graphical interface for the Microgateway.
You can download it using NPM via npm install -g apiconnect
. This toolkit can
be also be used for creating enterprise API definitions using IBM API Connect,
which provides features to create and manage APIs on an enterprise scale.
For more information, see https://developer.ibm.com/apiconnect/.
The API designer toolkit creates YAML files for the APIs definitions. These can then be tested directly on the internal Microgateway (part of the API Designer toolkit), or you can run them on an external Microgateway by moving the underlying YAML files to the external Microgateway directory.
The Microgateway was developed with the goal of making something simple, community-based, and that could easily be extended for anyone’s needs.
The Microgateway has the following characteristics:
A diagram of the Microgateway is shown below. Looking at the diagram, the flow of a request is from left to right. The Microgateway is a collection of middleware components that process the request in order. Each middleware component passes control to the next middleware until the processing of the request is complete. The postflow and error-handler middlewares work together to return the results back to the client making the request.
The urlrewrite middleware simply modifies the prefix of the URL under certain conditions. For the most part, this is a passthrough.
The context middleware creates a scratchpad memory area known as the context. The context is accessible by all middlewares and policies in the flow. Any middleware or policy can add, modify or remove variables from the context.
Here are some of the context variables that are automatically populated:
One object that is particularly important is the message object. The message object contains the payload that was received from a request. For example, if you add an invoke action, the results from that action will be placed in the message object. At the end of the flow, the contents of the message object will be returned back to the client.
Here are some other context variables:
The request object is another important object. It holds all of the information about the original request that was received by the Microgateway. There are other objects that contain system information, plan information, and general API information.
One important aspect of the context is that it is read-writable by policies and middleware as they execute. Another important factor is that context variables can be used as substitution parameters inside the conditional policies. This allows you to write sophisticated logic flows, simply referencing them through configuration.
The analytics middleware is used to connect to an external analytics engine. It passes a series of variables from the context in a message to an external collection device.
The preflow middleware accomplishes the following:
The flow-engine is a combinational processor that allows you to insert sequential logic around a series of policies. The policies can perform any operation to the request or response payload. They can be used to retrieve a response from an API backend or examine the request for security or other needs.
The flow-engine is built as a vendor extension to the standard Swagger
specification. The policies that are referenced in the assembly must have a
pre-built policy. Each one of the policies is a Node.js module that provides the
processing of the message. Each policy also has a policy.yml file that defines
the set of properties and behavior of the policy. For examples, visit the
policies
directory of the microgateway repository.
Following are the steps to install and run a stand alone microgateway
Step 1. Clone the microgateway repository
cd $HOME
git clone https://github.com/strongloop/microgateway.git
Step 2. Populate all of the necessary dependencies for the project
cd $HOME/microgateway
npm install
Step 3. Change current working directory to the root directory
cd $HOME/microgateway/
Step 4. Create a startup script that sets environment variables and starts up
the Microgateway. The script file is a simple node.js JavaScript file shown
below. Create this file in the $HOME/microgateway/
directory.
Note: The CONFIG_DIR is the folder containing the yaml files holding the API definitions that you wish to enforce.
// sample.js
//
'use strict';
var mg = require('./lib/microgw');
var fs = require('fs');
// config dir
process.env.CONFIG_DIR = __dirname + '/definitions/myapp';
process.env.NODE_ENV = 'production';
mg.start(3000);
Step 5. Create a yaml file to define the API. Place the yaml file in the folder
identified by the CONFIG_DIR
environment variable created in the startup script.
For this example, we are creating the file sample_1.0.0.yaml in the
$HOME/microgateway/definitions/myapp
directory. Note that you can place
several yaml files in this directory and all will be pulled in and used by the
Microgateway.
# sample_1.0.0.yaml
#
info:
version: 1.0.0
title: sample
description: sample laptop yaml
basePath: /sample
swagger: '2.0'
paths:
/echo:
get:
responses:
'200':
description: 200 OK
x-ibm-configuration:
assembly:
execute:
- javascript:
title: write a small json object
source: |
message.body = { text : 'Hello World' };
schemes:
- http
Step 6. From the root directory, execute the command to start the Microgateway.
cd $HOME/microgateway/
node sample.js
Step 7. Send a curl command to test the API. It should return the
{“text”:”Hello World”}
JSON object.
curl http://localhost:3000/sample/echo
For more information on the internal specifics of the Microgateway, you may want to look at the microgateway/test directory. All middleware components have one or more test suites to exercise their interfaces and logic.
For more examples on how to add various policies to your API assembly, look in the microgateway/test/definitions directory. There are several swagger files that are used to test out the implementation.
For information on contribuging to this project, please look at CONTRIBUTING.md and CONDUCT.md as well as the LICENSE.txt file.