Advanced Endpoints
Advanced Endpoints is a very powerful way to embed your corporate logic directly in the inmation Web API. This eliminates the need of the middleware between inmation and ERP or other business applications. For instance, inmation Web API can directly react on ERP HTTP requests and respond in a format, which is most suitable for the caller.
-
Allows advanced endpoint implementation.
-
Behave as a native endpoints.
-
Is able to route any URL.
-
Supports many HTTP methods.
-
Accepts various types of arguments
-
Response can be 'any' text based format
Description
The advanced endpoint embeds custom endpoints by hosting Lua libraries in the system. The name of the Lua library will be the first part of the custom path, the second part of the custom path will be the function name, unless the library returns a function itself. For example: api/v2/execfunction/corporate/readMachineHistory. In this example is corporate the name of the Lua library and readMachineHistory is a name of the function, which will be executed to process the request.
The implementation of the Advanced Endpoint is done in Lua. The Lua script will be stored as a library. Such a library can be implemented in two distinctive ways:
-
Returning an object (Lua table) containing function(s).
-
Returning one function.
The signature of the function is always the same. Containing three arguments: (arg, req, hlp).
-
(
arg
) argumentThis argument contains the body of the HTTP request.
-
(
req
) argument
A Lua table which contains the information about the request. The advanced endpoint accepts any path. The part of the path after the function name can be accessed by the path
field of the request req
argument. This can be used to handle routing withing Lua.
/api/v2/execfunction/corporate/readMachineData/lab/1234
This will result in the readMachineData
will be executed of the library corporate
where the /lab/1234
can be accessed on the req.path
parameter.
The provided query parameters in the URL are accessible through the query
field of the request req
argument. This field is a Lua table which contains the query parameter names as keys and query parameter values as strings. In case a query parameter is provided more than once this query table contains one entry of which the value is a Lua table string array.
The HTTP request type can be accessed by the method
field. This field contains one of the following string values: DELETE
, GET
, HEAD
, OPTIONS
, PUT
, POST
, PATCH
.
-
(
hlp
) argument
The hlp
argument is helper object which contains convenience functions, like checkpermission
and createResponse
.
The createResponse
function can be used to set the response body, error, HTTP status code and response headers, which should be returned by the Web API.
Extended explanation and examples of how to use the helper function can be found in the execfunction endpoint documentation
.
Examples
The Advanced Endpoint can make use of the standard logic in order to e.g. read historical data. This way it is very easy to add custom logic in combination with standard API functionality. The standard API logic can be accessed via the inmation.api
library.
Example - Read Historical Data
This simplified example reads historical data for one of the performance counters in which a caller only need to supply a start time.
local inAPI = require('inmation.api')
local lib = {}
function lib:readperfcounters(arg, req, hlp)
arg = arg or {}
local now = inmation.currenttime()
local startTime
if type(arg.starttime) == 'string' then
-- Use starttime supplied by the caller.
startTime = arg.starttime
else
-- Fallback to a default relative starttime
startTime = inmation.gettime(now-(5*60*1000))
end
local endTime = inmation.gettime(now)
local qry = {
start_time = startTime,
end_time = endTime,
intervals_no = 100,
items = {
{
p = "/System/Core/Performance Counter/Core/Core/CPU",
aggregate = "AGG_TYPE_INTERPOLATIVE"
}
}
}
return inAPI:readhistoricaldata(qry, req, hlp)
end
return lib
Invoke this endpoint by:
Method: POST
URL: /api/v2/execfunction/my-lib/readperfcounters
Body:
{
"start_time": "2019-04-02T10:00:00.000Z"
}
Example - Read Raw Historical Data with filter
This example shows how to read raw historical data for one of the performance counters. Start time and a value, which acts as a filter, are the parameters, which need to be supplied by the caller. The filter will only return values, which are greater than or equal to the provided value.
local inAPI = require('inmation.api')
local lib = {}
function lib:readperfcounters(arg, req, hlp)
arg = arg or {}
local now = inmation.currenttime()
local startTime
if type(arg.starttime) == 'string' then
-- Use starttime supplied by the caller.
startTime = arg.starttime
else
-- Fallback to a default relative starttime
startTime = inmation.gettime(now-(5*60*1000))
end
local endTime = inmation.gettime(now)
local qry = {
start_time = startTime,
end_time = endTime,
filter = {
v = {
["$gte"] = arg.limit or 50
}
},
items = {
{
p = "/System/Core/Performance Counter/Core/Core/CPU",
}
}
}
return inAPI:readrawhistoricaldata(qry, req, hlp)
end
return lib
Invoke this endpoint by:
Method: POST
URL: /api/v2/execfunction/my-lib/readperfcounters
Body:
{
"start_time": "2019-04-02T10:00:00.000Z",
"limit": 35
}
Example - Read Raw Historical Data and respond in CSV format
This example shows how to read raw historical data for one of the performance counters. Start time and a value, which acts as a filter,are the parameters, which need to be supplied by the caller. The filter will only return values which are greater than or equal to the provided value. The createResponse
helper function is used to set the Content-Type
of the response body to CSV format.
local inAPI = require('inmation.api')
local lib = {}
function lib:readperfcounters(arg, req, hlp)
arg = arg or {}
local now = inmation.currenttime()
local startTime
if type(arg.starttime) == 'string' then
-- Use starttime supplied by the caller.
startTime = arg.starttime
else
-- Fallback to a default relative starttime
startTime = inmation.gettime(now-(5*60*1000))
end
local endTime = inmation.gettime(now)
local qry = {
start_time = startTime,
end_time = endTime,
filter = {
v = {
["$gte"] = arg.limit or 50
}
},
items = {
{
p = "/System/Core/Performance Counter/Core/Core/CPU",
}
}
}
local respData = {}
local res = inAPI:readrawhistoricaldata(qry, req, hlp)
local rawData = res.data or {}
local histData = rawData.historical_data or {}
local queryData = histData.query_data or {}
if #queryData > 0 then
queryData = queryData[1]
local items = queryData.items or {}
if #items > 0 then
items = items[1]
for i,t in ipairs(items.t) do
local value = items.v[i]
local timestampISO = inmation.gettime(t)
local row = ("%s,%s"):format(timestampISO, value)
table.insert(respData, row)
end
end
end
local result = table.concat(respData, '\n')
return hlp:createResponse(result, nil, 200, { ["Content-Type"] = "text/csv" })
end
return lib
Invoke this endpoint by:
Method: POST
URL: /api/v2/execfunction/my-lib/readperfcounters
Body:
{
"start_time": "2019-04-02T10:00:00.000Z",
"limit": 35
}