List of available Plugins

Introduction

This page lists the plugins available out of the box in RESTHeart Platform.

List of Plugins

Inject properties with addRequestProperties

addRequestProperties is a transformer shipped with RESTHeart that allows to add some properties to the resource state.

The properties are specified via the args property of the transformer object. It is mainly intended to be applied to REQUESTs.

These properties are injected server side. If we need to store some information (such as the username) and we cannot rely on the client, this transformer is the solution.

An example is a blog application where each post document has the author property. This property could be valued server side via this transformer to avoid users to publish posts under a fake identity.

The properties that can be added are:

• userName
• userRoles
• dateTime
• localIp
• localPort
• localServerName
• queryString
• relativePath
• remoteIp
• requestMethod
• requestProtocol

For instance, the following request creates the collection rtsexample with this transformer applying to documents in the REQUEST phase. Looking at the args argument we can figure out that the request json data will be transformed adding the log object with the username of authenticated user and its remote ip.

PUT /rtsexample HTTP/1.1

{"rts":[{"name":"addRequestProperties","phase":"REQUEST","scope":"CHILDREN","args":{"log": ["remoteIp"]}}]}

If we now create a document, we can see the log property stored in the document because it was injected by RESTHeart in the request data.

PUT /rtsexample/mydoc HTTP/1.1

{"a":1}

HTTP/1.1 201 Created

GET /rtsexample/mydoc HTTP/1.1

HTTP/1.1 200 OK
{
    "_id": "mydoc", 
    "a": 1, 
    "log": {
        "remoteIp": "127.0.0.1"
    }
}

Filter out properties with filterProperties

filterProperties is a transformer shipped with RESTHeart that allows to filter out a the properties specified via the args property of the transformer metadata object.

The usual application of this transformer is hiding sensitive data to clients.

Let’s assume a collection called filterExample; we can remove the property secret from the response with the following filterProperties transformer.

PUT /filterExample HTTP/1.1

{"rts":[{"name":"filterProperties", "phase":"RESPONSE", "scope":"CHILDREN", "args":["secret"]}]}

Schema validation with checkContent

checkContent is a checker shipped with RESTHeart that allows to enforce a schema to the documents of a collection.

The schema definition is passed via the checker metadata args property as an array of conditions. A condition has the following format

{ "path": <json_path>, "type": <property_type>, "regex": <regex>, "nullable": boolean, "optional": boolean }

If the type is ‘object’ the properties mandatoryFields and optionalFields apply as well:

{ "path": <json_path>, "type": "object", "mandatoryFields": [ <field_names> ], "optionalFields": [ <field_names>] }

Json path expressions

A Json path expressions identifies a part of a Json document.

• It uses the dot notation where the special symbol $ identifies the document itself. 
• The special char * selects all the properties of an object.
• The special string [*] selects all the elements of an array.

the [n] notation is not supported, i.e. you cannot use the following json path expression $.array.[3] to select the n-th element of an array.

For example, given the following document:

{
    "_id": {
        "$oid": "55f6ccf4c2e6be404fdef3dd"
    },
    "string": "hello",
    "object": {
        "pi": 3.14,
        "href": "https://en.wikipedia.org/wiki/Pi"
    },
    "array": [1, 2, 3]
}

The following table shows what document parts, different json path expressions select:

Example

The following example creates the collection user enforcing its document to have following fields:

PUT /test/users HTTP/1.1

{ "checkers": [{
    "name": "checkContent",
    "args": [{
            "path": "$",
            "type": "object",
            "mandatoryFields": ["_id", "name", "password", "roles"],
            "optionalFields": ["bio"]
        },
        {
            "path": "$._id",
            "type": "string",
            "regex": "^\\u0022[A-Z0-9._%+-]+@[A-Z0-9.-]+\\u005C.[A-Z]{2,6}\\u0022$"
        },
        {
            "path": "$.password",
            "type": "string"
        },
        {
            "path": "$.roles",
            "type": "array"
        },
        {
            "path": "$.roles.[*]",
            "type": "string"
        },
        {
            "path": "$.name",
            "type": "string"
        },
        {
            "path": "$.bio",
            "type": "string",
            "nullable": true
        }
    ]
}]}

Limiting file size with checkContentSize

checkContentSize is a checker shipped with RESTHeart that allows to check the size of a request. It is very useful with file resources to limit the maximum size of the uploaded file.

The following example, creates a file bucket resource, limiting the file size from 64 to 32768 bytes:

PUT /test/icons.files HTTP/1.1

{ "descr":"icons",
  "checkers": [{
      "name":"checkContentSize",
      "args":{"min": 64, "max": 32768}
}]}