Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
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 with role = "hero" from hero as heroes with name = search.results.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 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.
- restql.b2w.io: Project home page, to get grasp of restQL,
- game.b2w.io: A game developed to teach the basics of restQL language,
- restQL-core: If you want to embed restQL directly into your Clojure application,
- restQL-core-java: If you want to embed restQL directly into your Java application,
- restQL-manager: To manage saved queries and resources endpoints. restQL-manager requires a MongoDB instance.
- Tackling microservice query complexity: Project motivation and history.
Running restQL Server
restQL Server allows you to post ad-hoc queries and to reference resources pre-configured in the server startup.
- Download the latest release in the release page,
- Unzip the package,
- Edit the file env.sh with the resources you want to invoke,
- Run bin/run.sh.
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.
Source and Docker
Building From Source Code
As prerequisites to build restQL-server from source we need:
- Java 8
Build the server using the build script:
The building script will create a folder
dist where you can configure your resources on the file
dist/bin/env.sh and run the server using the script
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=http://swapi.co/api/planets/" 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=http://swapi.co/api/planets/" 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.