Skip to content


Switch branches/tags

[_] Gateleen

Build Status codecov GitHub contributors

GitHub release Maven Central

Gateleen is a RESTFul middleware toolkit for building API gateways.

Getting Started


  • Clone this repository or unzip archive
  • Install and start Redis
    • Debian/Ubuntu: apt-get install redis-server
    • Fedora/RedHat/CentOS: yum install redis
    • OS X: brew install redis
    • Windows
    • Other


You need Java 8 and Maven

cd gateleen
mvn install

We're using a (private) mirror where we download npm/node from. In case you've no access to that mirror, you can use maven profile publicRepos (Eg: mvn install -PpublicRepos).


A Redis is needed for this


The gateleen-playground module provides a server example.

java -jar gateleen-playground/target/playground.jar

It starts on http://localhost:7012/playground

The storage is currently empty, that's why you get 404 Not Found

Upload some demo stuff using

mvn deploy -PuploadStaticFiles

The playground module provides a convenient web client for manipulating resources and a basic configuration.

Create your first resource with

curl -X PUT -d '{ "foo": "bar" }' http://localhost:7012/playground/hello/world

or any other REST Client

Now you can see the resource appear in http://localhost:7012/playground

Run integration tests

Once the playground is up the UI based integration tests can be executed using

mvn install -PuiIntegrationTests -Dsel_chrome_driver=/usr/local/chromedriver

there are also integration tests that are not based on the playground UI.

Note: Stop the playground prior to running these test:

mvn install -PnonUiIntegrationTests 


Module Description
core HTTP infrastructure and hierarchical resource storage that can be used as cache, intermediate storage for backend-pushed data, user and apps data
cache Cache JSON responses locally to reduce load on backends and increase performance.
delegate With the delegate feature a client is able to delegate requests to perform prespecified tasks.
delta Traffic optimization allowing clients to fetch only data that actually changed from the last time they fetched it
expansion Traffic optimization allowing clients to fetch a sub-tree of data in one request instead of many requests
hook Server push and callback support allowing backends to push data to clients and be notified when data is pushed by clients
integrationtest Test infrastructure
logging Logs request with configurable filtering for later data analysis
monitoring Monitor useful information like number of requests, queue sizes, etc.
packing Traffic optimization gathering multiple requests in one
performancetest Execute load tests using against a running playground instance
player Test tool to replay traffic recorded with gateleen-logging for automated tests and troubleshooting
playground Server example
qos Traffic priorization by rejecting requests to low-priority routes to keep more important features working when backends go down and load increases due to timeouts and retries
queue Request queuing to be robust to slow and available backends keeping the client connections short-lived
routing Configurable URL patterns and method based routing to backends and resource storage
runconfig Test infrastructure
scheduler Performs planned operations like data cleaning
security Fine grained authorization for URL patterns and methods against principal headers
test Integration tests
user Manages user profile merges user preferences and identity information
validation Validates data according to JSON schemas
kafka Forward requests to Kafka topics


This is a list of the custom headers used by Gateleen.

Header Description Link to documentation
x-rp-unique-id unique id
x-request-id id of the request (unique?)
x-self-request indicates if the request is triggered by a communication server and the target is the communication server itself
x-rp-grp group header gateleen-user
x-roles role header
x-delta used by the delta parameter to mark a delta request gateleen-delta
x-delta-backend used by the delta parameter as a marker header to know that we should let the request continue to the router gateleen-delta
x-expire-After indicates how long (in seconds) a request is 'valid' before it expires
x-hooked used by the HookHandler to indicate the original hook request as hooked gateleen-hook
x-pack-size indicates if a request is packed gateleen-packing
x-client-timestamp timestamp of the client while sending the request
x-server-timestamp timestamp of the server while sending the request
x-queue indicates a queued request gateleen-queue
x-duplicate-check indicates if a request is a duplicate or not
x-on-behalf-of indicates the user the request originally was made from. This header is used when the request of a user is sent by another user because it couldn't be sent at that time (offline)
x-user-<pattern> used for the user profile
x-rp-deviceid used to check if device is authorized
x-rp-usr used to check if user is authorized gateleen-user
x-rp-lang used to specify the language of the user profile gateleen-user
x-valid indicates if a request is to be validated or not gateleen-validation
x-service contains the name of the service, which created the request
x-queue-expire-after indicates how long (in seconds) a request is 'valid' in the queue before it expires

Performance Tuning

  • The amount of max open files per process should be at least 16384. You can check your max open files per process with this command cat /proc/<process id>/limits.
  • The amount of open files depends on the amount of open Http Requests, which are holding a tcp connection which are holding a file handle.
  • The important number to control the open Http Requests is the pool size of the Http Client. The higher the pool size the higher the open files.