restQL V3 is here

by Ricardo Mayerhofer

We’re pleased to announce the release of restQL V3! This major release includes a number of important features, such as:

• Content aggregation,
• Support for additional HTTP methods,
• A self-healing system,
• A JavaScript/ClojureScript version.
• Performance improvement (10x superior to GraphQL solutions such as Apollo)

Content aggregation

restQL makes easy to declare resources relationship in a query. e.g.:

from hero
    with
        name = "Restman"from sidekick
    with
        hero = hero.id

However, so far was up to the user to aggregate/consolidate to a single object when necessary, given restQL would always return them as separate objects in the query response:

{
  "hero": {
    "result": {
      "name": "Restman"
    },
  "sidekick": { 
    "result": {
      "name": "Super get"   
    }  
}

Now it’s possible to declare the content aggregation using the in operator and let restQL do the job. This makes even easier to query microservices transparently.

Query

from hero
    with
        name = "Restman"from sidekick in hero.mysidekick
    with
        hero = hero.id

Response

{
  "hero": {
    "result": {
      "name": "Restman", 
      "mysidekick": 
      { 
         "name": "Super get"
      }
  } 
}

Self-healing system

restQL should be able to make its way under heavy load

Being a key component between clients and APIs, resiliency needs to play a key role in restQL. Even if the underlying hardware is undersized, it should be able to gracefully deal with such scenarios and keep the requests going as much as possible.

To target this we’ve developed a self-healing system. When a given query gets few CPU slices (due high CPU usage), restQL starts to drop some requests by returning 507 (insufficient storage) while processing others. This alleviates CPU usage while keeps restQL responding.

The threshold is configured by setting the max_query_overhead_ms environment variable which sets the maximum allowed processing time overhead for a given query. When this threshold is reached the self-healing system is triggered. The default value is 50 ms.

Stress test: even under high-load restQL is still able to successfully (HTTP 200) process requests

Stress test: when max request overhead is reached the self-healing is triggered responding 507 for some requests

Additional HTTP methods support

As a REST and HTTP friendly tool restQL should support the most commonly used HTTP methods.

While V2 only supported GET operations, V3 supports GET, POST, PUT, AND DELETE operations. Those are translated to the following keywords respectively: from, to, into and delete. Example:

to users 
  with id = “user.id” 
    username = “user.name” 
    password = “super.secret”

When using to and into the parameters are passed in the request body, so the above query translates to:

POST http://some.api/users/ 
BODY { “id”: “user.id”, “username”: “user.name”, “password”: “super.secret” }

By combining different HTTP methods and saved queries, restQL offers a great way to control which parts of your APIs are externally visible.

Javascript package

Javascript has a big and growing community. To make it easier for javascript developers to start with restQL we’ve released restQL javascript support.

restQL-js allows developers to embed restQL directly into javascript without requiring spinning a separate HTTP server.

It currently only works in Node applications.

npm i @b2wdigital/restql

Code snippet:

var restlq = require('@b2wdigital/restql')// executeQuery(mappings, query, params, options) => <Promise>
restql
  .executeQuery(
    {user: "http://your.api.url/users/:name"},
    "from user with name = $name",
    { name: "Duke Nukem" })
  .then(response => console.log(response))
  .catch(error => console.log(error))

Performance improvement

restQL contributors worked hard to take performance to a new level. restQL v3 has a 2x improvement compared to its ancestor and handles 10x more requests compared to a popular GraphQL framework (Apollo GraphQL).

To make this happen, we’ve re-architected the orchestrating logic and replaced HTTP Kit with Aleph. Aleph is an asynchronous communication framework for Clojure built on top of the battle proven and high performant Netty.

More benchmark details can be found here.

Documentation

We still have a way to go on the project documentation, however we’ve improved the docs and moved it from GitHub wiki to a separate website using Docsify.

Upgrading

For V2 users restQL V3 is fully compatible, which means current users can upgrade seamlessly.

For V1 users it’s worth mentioning we had changes in multiplexed responses. In V1 a multiplexed response would generate an array of objects containing the result (payload) and the details (HTTP status and metadata).

"hero": [ {
  "result": {
    "name": "Restman"
  },
  "details": {
    "status": 200
  }
} ]

From V2 on multiplexed responses generates one array of results and another array of details. From users feedback we found that the latter format is easier to work with as you can get the result list and use it directly.

"hero": {
  "result": [{
    "name": "Restman"
  }],
  "details": [{
    "status": 200
  }]
}

That’s all (for now) folks

Interested? Get started querying microservices in 5 minutes: http://restql.b2w.io/

A special thanks for the great developers and contributors that made this release possible including @lucasbarros, @cupello, @machadolhes, @sio-iago and our community manager @josh

What’s next?

We’re working on functions specification. Functions allow fulfilling common orchestration tasks such as converting types and opens restQL language for extensibility. One goal is to make easy to implement and embed functions into the project.

from skillsto hero
    with
       name = "Restman" 
       skill = skills.name -> list-to-csv()

Example when there’s a need to convert a JSON list returned from one service to a CSV on another

We welcome community use cases and feedback on our draft: https://github.com/B2W-BIT/restQL-http/issues/67