API Macro

Api_macro module allows multiple REST API requests to be made with a single call. This decreases overhead and improves performance.

It also allows subsequent requests to refer to values from previous requests, making it easier to combine requests.

For example, to both an article (node/1) and also information about the author (user/1),
you could make two GET requests:
http://headless.dev/node/1?_format=json
and then
http://headless.dev/user/1?_format=json

With api_macro both requests can be combined in a single POST call:
http://headless.dev/api/v1.0/macro
with json payload:

{
    "requests": [
      "/node/1",
      "/user/1"
    ]
}

The individual responses are returned as elements in a json array. (We use POST instead of GET to allow for the json input. Each individual request is treated as though it were a a GET.)

So, two calls into are combined into one, getting the results in less time with less load on both front and back end. There is no limit on how many requests can be processed in one call, so the performance benefits could be substantial.

However, in many cases we would need to look at the result of the first request before we can make the second request. In the example above, we may not know the uid of the author until we look at the node. This is where the token comes into play. We can use a token in place of the author's uid:

{
    "requests": [
      "/node/1",
      "/user/<uid/target_id>"
    ]
}

Api_macro will execute the first request, getting the response for article node/1. Then, before the second request is processed, api_macro will search the result of the previous call and replace with the value of the uid. Then it will execute the second, modified, request.

The tokens include a top-level item in a previous response and the name of a next-level element containing the data, separated by a slash. The element names vary from item to item. For example, "/user/<uid/target_id>", "/node/<nid/value>", or "/comment/<comment/cid>".

Access Control

Each individual request is passed through an $entity->access('view') check.

Versions

The current code is built on Drupal 8.3. A Drupal 7 version is under construction.