API Builder Blocks

Introduction
Block definition
Example

Introduction

This guide covers the basics for creating Blocks. Blocks are functions that run before or after an API endpoint is executed. They can be used to modify the API request, to modify the API response or to execute common tasks like audit logging, caching, rate limiting or recording analytics. Multiple Blocks can be executed before or after an API request. Blocks are optional.

To programmatically create a Block, see the API Builder.Block API reference.

Block definition

Place all Block files in the project's blocks folder. You can only declare one Block per file. A Block file is a JavaScript file, which:

Loads the arrow module
Calls the module's Block.extend() method, passing in an object defining the block identifier and logic to execute
Exports the defined block using the module.exports variable

Set the following keys in the object passed to the Block.extend() method to define the Block:

Name	Required	Description
`name`	true	Block name. This name should be used when specifying blocks in your API endpoint definition. Assign the name value to either the `before` or `after` property in the API definition object to use it.
`description`	true	Human useful description to display in the documentation.
`execute`	true	The function containing the logic for your block. All of your runnable code goes in the `execute` function. This function is passed a `request`, `response`, and `next` object to be used within your block. Once you are done with your block code, always call `next()` to continue on to the next step in the request flow.
`documented`	false	Determines whether to generate API documentation (true) or not (false). The default value is `true`.

Example

The following Block replaces the id parameter to 2 and logs the change.

                      
                            var Arrow = require('arrow');
 
var PreBlock = Arrow.Block.extend({
    name: 'pre_example',
    description: 'will set a header named "Foo"',
 
    execute: function(req, res, next) {
        req.params.id = 2;
        req.log.info("Changing params.id to 2");
        next();
    }
});
 
module.exports = PreBlock;