Overview

The server leverages the API module to expose one or more URL endpoints. Each endpoint has a set of properties.

The properties decide behaviour of how to authenticate the calling client, how to treat incoming data and how to format the response back to the caller.

3.1.0

Scheduling added

This release allows for scheduling jobs

Basic

This configuration creates a public api on context /api/svc implemented by pipe api_pipe_01.

{
  "http_context" : "/api",
  "endpoints" : [ {
    "name" : "svc",
    "public": "true",
    "request": {
      "pipe" : "api_pipe"
    }
  } ]
}

Auth

{
  "http_context" : "/api",
  "endpoints" : [ {
    "name" : "svc",
    "auth" : {
      "pipe" : "auth_pipe"
    },
    "request": {
      "pipe" : "api_pipe"
    }
  } ]
}

Template

{
  "http_context" : "/api",
  "endpoints" : [ {
    "name" : "svc",
    "public" : true,
    "auth" : {
      "pipe" : "auth_pipe"
    },
    "request": {
      "pipe" : "api_pipe"
    },
    "response" : {
      "type" : "application/json",
      "template" : "{\n    \"now\": \"{{now}}\",\n    \"count\": {{items.size}},\n    \"elems\": [\n        {{#items}}\n        { \"id\": \"{{id}}\" }\n        {{/items}}\n    ],\n    \"response\": {{{response}}}\n}"
    }
  } ]
}

Custom status

{
  "http_context" : "/api",
  "endpoints" : [ {
    "name" : "svc",
    "public" : true,
    "response" : {
      "pipe" : "api_pipe",
      "status" : [ {
        "regex" : "Custom status.*",
        "value" : 444
      } ]
    }
  } ]
}

Client authentication is conducted through a PIPE. The PIPE involved in authentication has access to all data transmitted by the client. When designing an authentication PIPE, it's advisable to place the authentication data within the HTTP header.

A good design practice is to aim for lightweight authentication, especially since the client is authenticated with each request.

For enhanced security, don't rely solely on client authentication; if possible, incorporate additional layers of protection.

Updated default encryption

As of 3.1.0 default encryption has been changed. This will only affect systems where encryption is enabled.

To keep previous implementation ensure environment setting:

FORTIFIED_SECRETS_IMPL = local

Setting up a scheduled job

See separate documentation for scheduler module.

Instructions and information can be found here.

Verifying base installation

If running in container environment be sure to expose container port 8080.

Execute HTTP-POST to http://<host_or_ip>/api/demo/?secret=password

Response should look:

{
    "success": true,
    "data": {
        "items": [
            {
                "id": "result",
                "properties": {
                    "message": "This is the result from the API demo impl pipe"
                }
            }
        ]
    }
}

When a client invokes the API, the server initially cross-references the API configuration to determine if client authentication is required. If so, and if set up, authentication is processed through a PIPE. Only after successful authentication does the request get normalized and forwarded to the designated pipe for executing the core logic.

If the pipe executes without any errors, the response will carry an HTTP 200 status. Depending on the configuration and PIPE logic, the response body might include data.

On error API will return server 500 with potential error description. This can be changed using configuration.

Sending data to the API can be done by setting HTTP headers, request parameter or as a JSON structure in the request body.

Accessing data in a valve is done by using expansion.

Example

Given the http request with body:

{
	"firstkey": "fistvalue",
	"secondkey": "secondvalue"
}

Using expansion in valve to access "firstkey" is done through ${request.firstkey}.

Lets say the request sent in something in the http header Authorization header.

Expanding data in the Authorization haders is done: ${request.header_firstkey}.

Note the "header_" prefix.

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

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.

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.

"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.

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).

"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:

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.

"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.