Caio Ferreira edited this page Jul 15, 2018 · 45 revisions


restQL is a technology that enables data fetching orchestration from microservices. It offers the ability to register REST endpoints by name, send query parameters to the services, filter response fields and, most importantly, chain and parallelize requests. These and others features help reduce complexity on the client (front-end or others API's) in a clean, declarative and scalable way. For example:

from search
        role = "hero"

from hero as heroes
        name =

It works with a Query abstraction, that describes how the orchestration must be done, and can be run in two ways: with a standalone restQL Server or with restQL Embedded.

restQL Query

restQL stands for REST Query Language as it's the way we define the microservices orchestrations. You can learn all about the syntax here.


As stated, there are two ways to run restQL Queries:

  • Server: you can use a standalone restQL Server instance, that stores resource mappings, queries and executes them. Learn more here.
  • Embedded: you can add restQL as a dependency of your Java, learn here, or Clojure, learn here, application and use it internally to run queries and fetch data.

Useful links

Getting Started

Running restQL Server

restQL Server allows you to post ad-hoc queries and to reference resources pre-configured in the server startup.

  1. Download the latest release in the release page,
  2. Unzip the package,
  3. Edit the file with the resources you want to invoke,
  4. Run bin/

Post to http://your-server.ip:9000/run-query the following body:

from planets as allPlanets

Running restQL Manager

Manager now is a separate project available at restQL manager.

Next steps

  1. Learn restQL query language,
  2. Learn about the manager and saved queries,
  3. Get involved :)

Source and Docker

Building From Source Code

As prerequisites to build restQL-server from source we need:

  • Java 8
  • Leiningen

Build the server using the build script: scripts/

The building script will create a folder dist where you can configure your resources on the file dist/bin/ and run the server using the script dist/bin/

If you want to deploy restQL-server, copy the files under the generated dist folder and start the server using the start script above.

Running as a Docker container

Building Docker image

restQL-server can also be run as a Docker container. First, from the root folder, build a Docker image with the command:

docker build -t restql-server-img .

Running the container

Than run the image as a container with the command:

docker run -p 9000:9000 -e JAVA_OPTS="-Dmongo-url=mongodb://my-mongo-ip:27017/restql-server -Dplanets=" restql-server-img

You can register your APIs as resources by passing them in JAVA_OPTS environment variable, as seen above. The server default port is 9000 but it can be changed by passing the PORT environment variable with the desired port.

The MongoDB instance can also run from a container. If that's the case you can link to it and use its link name as the address:

docker run -p 27017-27017 --name mongo-docker mongo
docker run --link mongo-docker -p 9000:9000 -e JAVA_OPTS="-Dmongo-url=mongodb://mongo-docker:27017/restql-server -Dplanets=" restql-server-img

The MongoDB dependency is optional and is used to run saved queries.


Copyright © 2016-2017 B2W Digital

Distributed under the MIT License.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.