Action and search modules

Suppose you want to retrieve all users, that are registered on your service. You can’t use Action, because it returns only a single result. You will have to create a Search module for this.

The communication for Search is the same as for Action, except Search has an iterate directive, which specifies where are the items located inside the body.

For the next example, suppose that when you call /users on your service, you will get a list of users in body.data.

This example will correctly output each user that was returned:

{
    "url": "/users",
    },
    "response": {
        "output": "{{item}}",
        "iterate": "{{body.data}}",
        "limit": "{{parameters.limit}}"
    }
}

Iteration and pagination

An Action module should never contain pagination or the iterate directive. If you need to return multiple objects, create a Search module instead.

Wrong

Example of Wrong Implementation of Search Endpoint as Action Module

Right

Example of Correct Implementation of Search Module and Pagination Directive

Pagination parameters

The pagination section should only contain parameters directly influencing the actual pagination. These will be merged with the rest of the parameters defined in the qs section, so there is no need to define them all again.

Wrong

Example of Wrong Implementation of Pagination Directive

The pagination directive contains "since", "until" and "limit" parameters that are already defined in query string ("qs").

Right

Example of Correct Implementation of Pagination Directive

The pagination contains only the "offset" parameter.

Limiting output

The modules type Search and Trigger(polling) should return everything including by pagination. However, these modules should also allow users to limit their output, that is, how many bundles they return.

This can be achieved by setting up the limit parameter in the response. By default, this parameter is added to the Trigger (polling) modules and should be required. In Search modules, this parameter should NOT be required so if a user leaves it empty, the Search modules return everything. Its default value should be set to 10.

Search module limit example:

Communication

{
    "url": "/clients",
    "method": "GET",
    "qs": {
        "per_page": 100
    },
    "response": {
        "limit": "{{parameters.limit}}",
        "output": "{{item}}",
        "iterate": "{{body.clients}}"
    },
    "pagination": {
        "qs": {
            "page": "{{pagination.page}}"
        },
        "condition": "{{body.next_page}}"
    }
}

Mappable parameters

[
    {
        "name": "limit",
        "label": "Limit",
        "type": "uinteger",
        "help": "Number of clients to return",
        "default": 10
    }
]

The limit parameter should not be set to "required":true (except for polling trigger modules). The limit parameter should never be set to "advanced":true.