Custom API Gateway Service

Custom API for communication with end-user and external-client applications using HTTPS protocol.
Endpoints are configured from Murano portal interface under your solution routes or from exosite-cli tools.
Each request reaching your API endpoints will trigger the execution of your lua script. See the request event for more information.

Operations

Cors

Endpoint

File

Webservice_response

Events

Operations

Cors


getCors

Retrieve the API cross-origin HTTP request policy settings.

Responses
API cross-origin HTTP request policy settings. Find more about Cors on https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS - object
Name Type Description
origin [ string ] If set to false CORS are not activated for the API If true all domain are Allowed If array list of allowed domains
headers [ string ] Set Access-Control-Allow-Headers header value
methods [ "GET", "PUT", "POST", "DELETE", "PATCH", "WEBSOCKET" ] Set Access-Control-Allow-Methods header value
credentials boolean Set Access-Control-Allow-Credentials header value
expose_headers [ string ] Set Access-Control-Expose-Headers header value
Error response - object
Name Type Description
code string Response code
type string Error type
message string Error message

setCors

Set the API cross-origin HTTP request policy settings.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
origin [ string ] If set to false CORS are not activated for the API If true all domain are Allowed If array list of allowed domains
headers [ string ] Set Access-Control-Allow-Headers header value
methods [ "GET", "PUT", "POST", "DELETE", "PATCH", "WEBSOCKET" ] Set Access-Control-Allow-Methods header value
credentials boolean Set Access-Control-Allow-Credentials header value
expose_headers [ string ] Set Access-Control-Expose-Headers header value
Responses
CORS settings updated - nil

CORS settings updated

Error response - object
Name Type Description
code string Response code
type string Error type
message string Error message

Endpoint


createEndpoint

Create an API endpoint.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
id string Unique Id representing this endpoint
path ^(\/(\w+[:-]?\w*\ {[a-zA-Z]+}))*\/?$ Endpoint path
method "GET", "PUT", "POST", "DELETE", "PATCH", "WEBSOCKET" The HTTP method supported by this endpoint route.
script string(lua) Lua script executed when this endpoint recieve a request.
content_type "application/json", "text/plain", "application/x-www-form-urlencoded", "application/octet-stream", "multipart/form-data" Mime type of the expected Http request body consumed by the endpoint
Default: "application/json"
use_basic_auth boolean In indicates this endpoint use basic authentication check as defined by RFC2617. The user credentials are checked agains the users set in the solution User service.
Responses
Endpoint information - object
Name Type Description
id string Endpoint Id
Error response - object
Name Type Description
code string Response code
type string Error type
message string Error message

deleteEndpoint

Delete an API endpoint.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
endpoint_id string The endpoint Id
Responses
Endpoint deleted - nil

Endpoint deleted

Error response - object
Name Type Description
code string Response code
type string Error type
message string Error message

getEndpoint

Retrieve an API endpoint information.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
endpoint_id string The endpoint Id
Responses
An API endpoint definition. - object
Name Type Description
id string Unique Id representing this endpoint
path ^(\/(\w+[:-]?\w*\ {[a-zA-Z]+}))*\/?$ Endpoint path
method "GET", "PUT", "POST", "DELETE", "PATCH", "WEBSOCKET" The HTTP method supported by this endpoint route.
script string(lua) Lua script executed when this endpoint recieve a request.
content_type "application/json", "text/plain", "application/x-www-form-urlencoded", "application/octet-stream", "multipart/form-data" Mime type of the expected Http request body consumed by the endpoint
Default: "application/json"
use_basic_auth boolean In indicates this endpoint use basic authentication check as defined by RFC2617. The user credentials are checked agains the users set in the solution User service.
Error response - object
Name Type Description
code string Response code
type string Error type
message string Error message

getSwagger

Retrieve the API Swagger schema.

Responses
Swagger schema as defined by http://swagger.io/specification/ - object
Name Type Description
Error response - object
Name Type Description
code string Response code
type string Error type
message string Error message

listEndpoints

Retrieve the list of the API endpoints.

Responses
Endpoints list. - [ object ]
Name Type Description
id string Unique Id representing this endpoint
path ^(\/(\w+[:-]?\w*\ {[a-zA-Z]+}))*\/?$ Endpoint path
method "GET", "PUT", "POST", "DELETE", "PATCH", "WEBSOCKET" The HTTP method supported by this endpoint route.
script string(lua) Lua script executed when this endpoint recieve a request.
content_type "application/json", "text/plain", "application/x-www-form-urlencoded", "application/octet-stream", "multipart/form-data" Mime type of the expected Http request body consumed by the endpoint
Default: "application/json"
use_basic_auth boolean In indicates this endpoint use basic authentication check as defined by RFC2617. The user credentials are checked agains the users set in the solution User service.
Error response - object
Name Type Description
code string Response code
type string Error type
message string Error message

updateEndpoint

Update an API endpoint.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
endpoint_id string The endpoint Id
id string Unique Id representing this endpoint
path ^(\/(\w+[:-]?\w*\ {[a-zA-Z]+}))*\/?$ Endpoint path
method "GET", "PUT", "POST", "DELETE", "PATCH", "WEBSOCKET" The HTTP method supported by this endpoint route.
script string(lua) Lua script executed when this endpoint recieve a request.
content_type "application/json", "text/plain", "application/x-www-form-urlencoded", "application/octet-stream", "multipart/form-data" Mime type of the expected Http request body consumed by the endpoint
Default: "application/json"
use_basic_auth boolean In indicates this endpoint use basic authentication check as defined by RFC2617. The user credentials are checked agains the users set in the solution User service.
Responses
Endpoint updated - nil

Endpoint updated

Error response - object
Name Type Description
code string Response code
type string Error type
message string Error message

File


deleteFile

Remove the static file.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
path string The API path where file is located
Responses
Files deleted successfully - nil

Files deleted successfully

Error response - object
Name Type Description
code string Response code
type string Error type
message string Error message

headFile

As get the file but dont return the actual content.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
path string The API path where file is located
Responses
Files accessible - nil

Files accessible

Error response - object
Name Type Description
code string Response code
type string Error type
message string Error message

listFiles

Retrieve the list of static files.

Responses
Files list. - [ object ]
Name Type Description
path string API path to retrieve the file
checksum string File checksum
mime_type string File mime type
Error response - object
Name Type Description
code string Response code
type string Error type
message string Error message

Webservice_response


apiReply

Reply to a pending API HTTP request with a standard HTTP response. This operation is used after receiving a webservice request event.
When using Murano endpoint script, you DO NOT need to use this operation manually as the Murano webservice router already handles it for you at the end of the endpoint script execution.

However, if you want to set your own endpoint routing mechanism, you can directly edit your solution webServer request eventHandler script. In such case the Webservice.apiReply needs to be called manually and the request_id and service_id parameters have to be provided.
Important! Any endpoint script changes will reset the default routing mechanism and eventHandler script changes will be lost. The default timeout of endpoint script is 120 seconds with upper limit of 10 seconds cpu time, when either reached, client end will receive 504.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
request_id string The request ID provided in the request data. Automatically set when using Murano endpoint script.
code integer {..999} The HTTP response status code
Default: 200
headers object HTTP response headers
message string The HTTP response body content. From endpoint scripts, Lua Table are transformed to the equivalent JSON structure.
(deprecated) server_ip string(ipv4) The server IP address holding the HTTP connection. Provided in request data. Automatically set when using Murano endpoint script.
Responses
Response successfully sent - nil

Response successfully sent

Error response - object
Name Type Description
code string Response code
type string Error type
message string Error message
Example
-- In webservice endpoint script:
response.code = 201 response.message = {hello = "world"} response.headers["x-my-custom-header"] = "my header content"
-- In webservice eventHandler script:
local responseData = {
  ["request_id"] = request.request_id,
  code = 201,
  message = "{\"hello\":\"world\"}",
  headers = { ["content-type"] = "application/json" }
} Webservice.apiReply(responseData)

Events


request

An HTTP request has reached your custom API endpoint and triggers the webservice eventHandler script execution. This request is waiting for a response through the apiReply operation.
All requests trigger the same eventHandler script. However, for your convenience, Murano provides out-of-the-box endpoint routing wrapper triggering endpoint scripts.
So when writing an endpoint script, you simply use the response parameters or directly return the desired response body content. As the apiReply response is automatically made at the end of each endpoint scripts by the Murano routing wrapper.

However, if you want to set your own endpoint routing mechanism, you can directly edit your solution webServer eventHandler script. See apiReply operation for more information.
Important! Any endpoint script changes will reset the default routing mechanism and eventHandler script changes will be lost.

Endpoint script default values:
response.code: 200
response.message: "Ok"
response.headers["content-type"] = "text/plain" if message is a "string", "application/json" otherwise.

Arguments
request - object - The HTTP request data
Name Type Description
uri string The request complete URI including API domain name.
body object, string The HTTP request json body content. JSON data will be decoded automatically in a Lua table structure. Otherwise a string is provided.
route string The endpoint path, matching the custom API endpoint configuration on Murano portal
method "POST", "PUT", "GET", "DELETE", "PATCH", "OPTION" The HTTP method of the request, matching the custom API endpoint configuration on Murano portal
headers object The HTTP request headers
server_ip string(ipv4) The address of the API server holding the pending HTTP request. Only for webservice eventhandler scripts when calling apiReply operation.
timestamp integer HTTP request reception time as Unix timestamp.
parameters object The HTTP request query parameters as a Map containing both from path and query parameters.
Path parameters are set on the Murano portal routes by using '/myendpoint/{pathParameterName}'. Query parameters are dynamically set from the url parameters following the format '/myendpoint?queryParameterNameOne=hello&queryParameterNameTwo=world'.
request_id string Unique request ID use to match with the response. Only for webservice eventhandler scripts when calling apiReply operation.
Example
-- In a webservice endpoint script:
response.code = 201 response.message = {hello = "world"} response.headers["x-my-custom-header"] = "my header content"
-- Same behavior in EventHandler script:
function handle_webservice_request (request)

  local responseData = {
    ["request_id"] = request.request_id,
    code = 201,
    message = "{\"hello\":\"world\"}",
    headers = { ["content-type"] = "application/json" }
  }
  Webservice.apiReply(responseData)

end