Configuration

API requires module API to be deployed. If endpoints are implemented in Pipes, the Pipes module must be deployed.

Since API is based on HTTP all HTTP configuration properties are supported. Find global settings here.

Properties

Name	Description
http_context	Base context (Default: "/api")
endpoints	List of api endpoint configurations

Example

{
  "http_context" : "/api01",
  "endpoints" : [ ]
}

Endpoint configuration

Each API endpoint represents an API with a unique context path and configurable authentication and request/response data. Endpoint logic can be implemented by a pipe but it is not required.

Properties

Name	Description
name	Endpoint name (Mandatory)
context_path	Endpoint relative path (Optional, defaults to name)
public	Flag turning on/off authentication for this endpoint (Default: false)
auth.*	Endpoint authentication configuration
auth.pipe	Id of pipe performing endpoint authentication. Authentication is successful if pipe returns success, otherwise authentication fails. Request and response handlers are only called if authentication is successful.
request.*	Request configuration (see below for handler specific configuration)
request.handler	Name of request handler (Default: "Pipes")
response.*	Response configuration (see below for handler specific configuration)
response.handler	Name of response handler (Default: "Pipes")

Example

{
    "name" : "svc01",
    "public" : true,
    "auth" : {
      "pipe" : "auth_pipe_01"
    },
    "request" : {
      "handler" : "DataProxy",
      "pipe" : "api_pipe_01"
    },
    "response" : {
      "handler" : "DataProxy"
    }
}

Request handlers

The request handler is a pluggable component responsible for processing the endpoint HTTP request.

Pipes

This is the default handler. Converts the API HTTP request to a pipe request containing the body, configured headers and params and request properties.

Properties

Name	Description
pipe	Id of pipe implementing the endpoint
headers	List of headers to include in pipe request. (Default: null, no headers are included)
params	List of parameters (query and/or form) to include in pipe request. (Default: "*", all params are included)
session_overload	Flag to enable session overload (i.e use specific session when calling pipes) (Default: false)
session_id	Name of request parameter containing session id for session overloading. (Default: "__session_id")

Example

"request": {
    "handler": "Pipes",
    "pipe": "pipe_01",
    "headers": "Host",
    "params": "*",
    "session_overload": true,
    "session_id": "token"
}

ProxyData

This request handler proxies request data (i.e. the body) without modifications to a pipe. If request data is a form a new pipe request will be built containing all form params.

Response handlers

The response handler is a pluggable component responsible for producing the endpoint HTTP response.

Response handlers can only be combined with request handlers producing a compatible output.

Pipes

This is the default handler. Operates on pipe responses that may contain items. Produces a custom response body using a template or returns the pipe response as-is if no template is configured (JSON).

Properties

Name	Description
content_type	Response content type
template	Response template (see below)
status	Custom status configuration (see below)

Example

"response": {
    "handler": "Pipes",
    "content_type": "application/json",
    "template": ""
}

ProxyData

Response handler creating a response from a pipe response containing headers and body properties.

Response templating

When using the Pipes response handler, the response can be transformed to any text format using a template.

Template scope objects

The following object are available during template rendering:

Name	Description
items	List of response items
response	The actual response
util.now	Current date/time as an ISO instant
util.uuid	Create UUID

Example template

{
    "now": "{{util.now}}",
    "count": {{items.size}},
    "elems": [
        {{#items}}
        { "id": "{{id}}" }
        {{/items}}
    ]
}

{{{response}}}

Status mapping

Pipe response reason can be mapped to a custom HTTP status code by using status mappings.

Mappings are processed in the defined order, first match wins.

Properties

Name	Description
regex	Regular expression matched against reason string
value	The HTTP status code returned on match

Example

"status": [
  {
    "regex" : "Not found",
    "value" : 404
  },
  {
    "regex" : "Custom status.*",
    "value" : 444
  },
  {
    "regex" : ".{1,}",
    "value" : 500
  }  
]

Default configuration file

Attached is the default config.json file used when starting the default configuration.

2KB

config.json