akera-rest-api

REST API module for Akera.io web service - call any business logic procedure through this REST interface.

Installation

$ npm install akera-rest-api

Docs

• Website and Documentation

Quick Start

This module is designed to only be loaded as broker level service which is usually done by adding a reference to it in services section of each broker's configuration in akera-web.json configuration file.

  "brokers": [
    {	"name": "demo",
        "host": "localhost",
        "port": 3737,
        "services": [
            { 
                "middleware": "akera-rest-api",
                "config": {
                    "route": "/rest-api/"
                }
            }
        ]
    }
  ]

Service options available: - route: the route where the service is going to be mounted (default: '/rest/api/')

The interface can then be used to call business logic procedures on the broker by making HTTP POST requests to http://[host]/[broker]/rest-api/ and send call information using the call request parameter as a JSON object with following structure - wrapping it all in a call object is optional:

- `procedure`: the business logic procedure name
- `parameters`: array of optional procedure parameters, must match the procedure parameters else an error will be thrown back. 
    Each parameter entry has the following structure:
    - `dataType`: parameter data type
        - valid values: `character`, `date`, `datetime`, `dataset`, `decimal`, `integer`, `int64`, `logical`, `longchar`, `memptr`, `table`
        - defaults to `character`
    - `type`: parameter type/direction
        - valid values: `input` | `i`, `input-output` | `inout` | `io`, `output` | `out` | `o`
        - defaults to `input`
    - `value`: parameter value for input/input-output parameters
    - `json`: for output/input-output parameters of type character/longchar.
        If set to true the value is sent as a JSON object instead of encoding it as a string. 
        Dataset and table parameters are always sent as JSON objects.

The request must have the Content-Type header value set to application/json in order to be correctly interpreted by the REST service handler.

Only procedures available in akera.io application server WEBPATH can be executed - not everything from agent's PROPATH is available through the REST API interface.

All Progress primitive data types are supported as input/output/input-output parameters, for output complex data types like table and dataset are also supported.

    { "call": {
            "procedure": "crm/getCustomerBalance.p",
            "parameters": [
                {
                    "value": 12
                },
                {
                    "type": "output",
                    "dataType": "decimal"
                },
                {
                    "type": "output",
                    "dataType": "decimal"
                }
            ]
        }
    }

or

    {
        "procedure": "crm/getCustomerComplaints.p",
        "parameters": [
            {
                "value": 12 // customer number
            },
            {
                "type": "input-output",
                "dataType": "integer" // start record
            },
            {
                "type": "output",
                "dataType": "longchar",
                "json": true
            }
        ]
    }

The response is a JSON object with either a parameters array or an error object, only output and input-output parameters are sent back in the parameters array keeping the same order as in the input parameters array.

Change log

As of version 1.0.8 the interface also support GET requests with procedure and parameters values passed through the query string value, also on POST requests the call wrapper object is no longer mandatory - procedure and parameters can be sent directly into the root JSON object.

As of version 1.0.10 the interface also support json flag for output/input-output string parameters (characters/longchar).

License

MIT