REST API Gateway Service¶

Summary¶

Enable web-based, HTTPS-encrypted access to your solution's API, websocket channels and static assets file.

Each request to your API endpoints will trigger the execution of the related scripts.

Endpoints defined in the API are automatically documented using the openapi v2.0 format from the '/swagger.json' & '/swagger.yaml' endpoint and displayed in the '/docs' endpoint.

Operations

Name	Tag	Summary
webservice.getCors()	Cors	Get the API CORS
webservice.setCors()	Cors	Set the API CORS
webservice.createEndpoint()	Endpoint	Create endpoint
webservice.deleteEndpoint()	Endpoint	Delete endpoint
webservice.getEndpoint()	Endpoint	Get an endpoint
webservice.getSwagger()	Endpoint	Get the Swagger schema
webservice.listEndpoints()	Endpoint	List the endpoints
webservice.updateEndpoint()	Endpoint	Update endpoint
webservice.deleteFile()	File	Delete a file
webservice.headFile()	File	Get file headers
webservice.listFiles()	File	List API static files
webservice.updateFile()	File
(deprecated) webservice.apiReply()	Other	Reply to API request

Events

Name	Summary
request	HTTP request

Configuration parameters¶

Name	Type	Description
domain	^[a-zA-Z0-9-]{1,63}$\\\.\[a-zA-Z0-9-\]\{1,63\}$*$	The public domain name used for the API. IMPORTANT: Only last subdomain can be changed. To use a custom domain, contact Exosite support.
cors	object	Restrictions on how the API should be accessed by client websites to increase navigation security. Find more about CORS on https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
cors.origin	[ ^$\\\\|\(\[a-z\]\+:\\/\\/\(\\\?\|\[a-zA-Z0-9-\]\+$$\\\.\[a-zA-Z0-9-\]\+$?$:\(\\\\|\[0-9\]\+$)?))$ ]	List of allowed domains. Default: []
cors.headers	[ string ]	Set Access-Control-Allow-Headers header value
cors.methods	[ "HEAD", "GET", "PUT", "POST", "DELETE", "PATCH", "OPTIONS" ]	Set Access-Control-Allow-Methods header value
cors.credentials	boolean	Set Access-Control-Allow-Credentials header value
cors.expose_headers	[ string ]	Set Access-Control-Expose-Headers header value
headers	object	Http headers
headers.^[\w-]{1,200}$	string	Header value
documented_endpoints	[ string {..40} ] {..10}	List of tags used to filter which endpoints to expose to public documentation.
security_schemes	[ object ]	The security schemes supported by the API. You need to specify in the 'security' parameter which scheme to use for which endpoints. Default: []
security_schemes[].in	"header", "query", "cookie"	For `type=apiKey` only, the place to put token.
security_schemes[].name	string	For `type=apiKey` only. The name of parameter or header to find the apiKey.
security_schemes[].type	"bearer", "basic", "apiKey"	The authentication type. It could be `basic`, `bearer`, `apiKey` etc.
security	[ "none", "basic", "bearer", "apiKey" ]	The authentication method for all endpoints. Select from the security schemes. Default: []
rate_limit	integer	Request rate limit per token per minute. Default is 0, meaning no limit.
api_info	object	Info for the auto-generated swagger API.
api_info.title	string	Title of your solution API.
api_info.contact	object	Contact info of your solution API.
api_info.contact.name	string	Your name
api_info.contact.email	string(email)	Your email
api_info.version	string	Version of your solution API. Default: "v1"
api_info.description	string	A description of your solution API.

Operations¶

getCors¶

Description

Retrieve the API cross-origin HTTP request policy settings.

Responses

Returns {object} when Cross-origin HTTP request policy

Restrictions on how the API should be accessed by client websites to increase navigation security.Find more about CORS on https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS {object}

Name Type Description

origin [ ^$\\\*|\(\[a-z\]\+:\\/\\/\(\\\*?|\[a-zA-Z0-9-\]\+$$\\\.\[a-zA-Z0-9-\]\+$*?$:\(\\\*|\[0-9\]\+$)?))$ ] List of allowed domains.
Default: []

headers [ string ] Set Access-Control-Allow-Headers header value

methods [ "HEAD", "GET", "PUT", "POST", "DELETE", "PATCH", "OPTIONS" ] 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

Returns {object} when Failed to retrieve schema

Error response {object}

Name Type Description

code string Response code

type string Error type

message string Error message

setCors¶

Description

Set the API cross-origin HTTP request policy settings.

Arguments

Name	Type	Description
origin	[ ^$\\\\|\(\[a-z\]\+:\\/\\/\(\\\?\|\[a-zA-Z0-9-\]\+$$\\\.\[a-zA-Z0-9-\]\+$?$:\(\\\\|\[0-9\]\+$)?))$ ]	List of allowed domains. Default: []
headers	[ string ]	Set Access-Control-Allow-Headers header value
methods	[ "HEAD", "GET", "PUT", "POST", "DELETE", "PATCH", "OPTIONS" ]	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

Returns nil for CORS settings updated
Returns {object} when Failed to retrieve schema

Error response {object}

Name Type Description

code string Response code

type string Error type

message string Error message

createEndpoint¶

Description

Create an API endpoint.

Arguments

Name	Type	Description
id	string	Unique Id representing this endpoint
path	^$\\/\(\\w\+\[:-\]?\\w\\|\{\[a-zA-Z\]\+\}$)$\\/\(\\w\+\(\[:\.-\]\\w\+$?)?)?$	Endpoint path. Notice endpoints with/without trailing slashes are different in webservice for any non-root endpoints.
tags	[ string {..40} ] {..10}	List of swagger tags for the endpoint.
method	"GET", "PUT", "POST", "DELETE", "PATCH", "WEBSOCKET"	The HTTP method supported by this endpoint route.
script	string(lua)	Lua script executed when this endpoint receive a request.
security	[ "none", "basic", "bearer", "apiKey" ]	The authentication method for all endpoints. Select from the security schemes. Default: []
responses	object	The responses of the endpoint. Check https://swagger.io/docs/specification/2-0/describing-responses/ for more details.
parameters	array	The request parameters of the endpoint. Check https://swagger.io/docs/specification/2-0/describing-parameters/ for more details.
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 against the users set in the solution User service.

Responses

Returns {object} for Endpoint information

Name Type Description

id string Endpoint Id
Returns {object} when Failed to create endpoint

Error response {object}

Name Type Description

code string Response code

type string Error type

message string Error message

deleteEndpoint¶

Description

Delete an API endpoint.

Arguments

Name	Type	Description
endpoint_id	string	The endpoint Id

Responses

Returns nil for Endpoint deleted
Returns {object} when Failed to delete endpoint

Error response {object}

Name Type Description

code string Response code

type string Error type

message string Error message

getEndpoint¶

Description

Retrieve an API endpoint information.

Arguments

Name	Type	Description
endpoint_id	string	The endpoint Id

Responses

Returns {object} when Endpoint retrieved

An API endpoint definition. {object}

Name Type Description

id string Unique Id representing this endpoint

path ^$\\/\(\\w\+\[:-\]?\\w\*|\{\[a-zA-Z\]\+\}$)*$\\/\(\\w\+\(\[:\.-\]\\w\+$?)?)?$ Endpoint path. Notice endpoints with/without trailing slashes are different in webservice for any non-root endpoints.

tags [ string {..40} ] {..10} List of swagger tags for the endpoint.

method "GET", "PUT", "POST", "DELETE", "PATCH", "WEBSOCKET" The HTTP method supported by this endpoint route.

script string(lua) Lua script executed when this endpoint receive a request.

security [ "none", "basic", "bearer", "apiKey" ] The authentication method for all endpoints. Select from the security schemes.
Default: []

responses object The responses of the endpoint. Check https://swagger.io/docs/specification/2-0/describing-responses/ for more details.

parameters array The request parameters of the endpoint. Check https://swagger.io/docs/specification/2-0/describing-parameters/ for more details.

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 against the users set in the solution User service.

Returns {object} when Failed to retrieve endpoint

Error response {object}

Name Type Description

code string Response code

type string Error type

message string Error message

getSwagger¶

Description

Retrieve the API Swagger schema.

Responses

Returns {object} for Swagger schema as defined by http://swagger.io/specification/

Name Type Description
Returns {object} when Failed to retrieve schema

Error response {object}

Name Type Description

code string Response code

type string Error type

message string Error message

listEndpoints¶

Description

Retrieve the list of the API endpoints.

Responses

Returns {[ object ]} for Endpoints list.

Name Type Description

id string Unique Id representing this endpoint

path ^$\\/\(\\w\+\[:-\]?\\w\*|\{\[a-zA-Z\]\+\}$)*$\\/\(\\w\+\(\[:\.-\]\\w\+$?)?)?$ Endpoint path. Notice endpoints with/without trailing slashes are different in webservice for any non-root endpoints.

tags [ string {..40} ] {..10} List of swagger tags for the endpoint.

method "GET", "PUT", "POST", "DELETE", "PATCH", "WEBSOCKET" The HTTP method supported by this endpoint route.

script string(lua) Lua script executed when this endpoint receive a request.

security [ "none", "basic", "bearer", "apiKey" ] The authentication method for all endpoints. Select from the security schemes.
Default: []

responses object The responses of the endpoint. Check https://swagger.io/docs/specification/2-0/describing-responses/ for more details.

parameters array The request parameters of the endpoint. Check https://swagger.io/docs/specification/2-0/describing-parameters/ for more details.

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 against the users set in the solution User service.

Returns {object} when Failed to retrieve endpoint list

Error response {object}

Name Type Description

code string Response code

type string Error type

message string Error message

updateEndpoint¶

Description

Update an API endpoint.

Arguments

Name	Type	Description
endpoint_id	string	The endpoint Id
id	string	Unique Id representing this endpoint
path	^$\\/\(\\w\+\[:-\]?\\w\\|\{\[a-zA-Z\]\+\}$)$\\/\(\\w\+\(\[:\.-\]\\w\+$?)?)?$	Endpoint path. Notice endpoints with/without trailing slashes are different in webservice for any non-root endpoints.
tags	[ string {..40} ] {..10}	List of swagger tags for the endpoint.
method	"GET", "PUT", "POST", "DELETE", "PATCH", "WEBSOCKET"	The HTTP method supported by this endpoint route.
script	string(lua)	Lua script executed when this endpoint receive a request.
security	[ "none", "basic", "bearer", "apiKey" ]	The authentication method for all endpoints. Select from the security schemes. Default: []
responses	object	The responses of the endpoint. Check https://swagger.io/docs/specification/2-0/describing-responses/ for more details.
parameters	array	The request parameters of the endpoint. Check https://swagger.io/docs/specification/2-0/describing-parameters/ for more details.
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 against the users set in the solution User service.

Responses

Returns nil for Endpoint updated
Returns {object} when Failed to update endpoint

Error response {object}

Name Type Description

code string Response code

type string Error type

message string Error message

deleteFile¶

Description

Remove the static file.

Arguments

Name	Type	Description
path	string	The API path where file is located

Responses

Returns nil for Files deleted successfully
Returns {object} when Failed to delete file

Error response {object}

Name Type Description

code string Response code

type string Error type

message string Error message

headFile¶

Description

As get the file but don't return the actual content.

Arguments

Name	Type	Description
path	string	The API path where file is located

Responses

Returns nil for Files accessible
Returns {object} when Failed to access file

Error response {object}

Name Type Description

code string Response code

type string Error type

message string Error message

listFiles¶

Description

Retrieve the list of static files.

Responses

Returns {[ object ]} for Files list.

Name Type Description

path string API path to retrieve the file

checksum string File checksum

mime_type string File mime type
Returns {object} when Failed to retrieve file list

Error response {object}

Name Type Description

code string Response code

type string Error type

message string Error message

updateFile¶

Description

Update file metadata

Arguments

Name	Type	Description
file	string	The API path where file is located
path	string	API endpoint to access the file.

Responses

Returns nil for File updated
Returns {object} when Failed to update file

Error response {object}

Name Type Description

code string Response code

type string Error type

message string Error message

Other¶

apiReply [deprecated]¶

Description

This operation is DEPRECATED As of latest update the response object can be directly returned from the eventhandler. 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

Name	Type	Description
request_id	string	The request ID provided in the request data. Automatically set when using Murano endpoint script.
code	integer	The HTTP response status code Default: 200
file	string	API path corresponding to a file to return as this request response
headers	object	HTTP response headers
message	string	The HTTP response body content. From endpoint scripts, Lua Table are transformed to the equivalent JSON structure.

Responses

Returns nil for Response successfully sent
Returns {object} when Fail to send the HTTP response. More information is available in the operation response.

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" }
}
return responseData

Events¶

request¶

Description

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

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.
files	[ object ]	Files uploaded as multipart/form-data and cashed until the request is responded. Can be used to persist the file as part of the solution Assets and directly available through the given Webservice endpoint path. See documentation for: Asset.store({["file_id"] => request.files[1].file_id, ["request_id"] = request.request_id, path = "/api/location"})
files[].size	integer	File size in bytes
files[].file_id	string	Temporary file id to use for persisting the file in the Asset service
files[].encoding	string	File encoding
files[].mimetype	string	File mime type
files[].fieldname	string	Multipart formdata name
files[].originalname	string	Name of the file from uploaded origin
route	string	The endpoint path, matching the custom API endpoint configuration on Murano portal
method	"POST", "PUT", "GET", "DELETE", "PATCH", "WEBSOCKET"	The HTTP method of the request, matching the custom API endpoint configuration on Murano portal
headers	object	The HTTP request headers as "<header name>":"<header value>"
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.

Responses

Returns {object} when Response content to the http request.

The request response data to reply to the client. {object}

Name Type Description

code integer The HTTP response status code
Default: 200

file string API path corresponding to a file to return as this request response

headers object HTTP response headers

message string The HTTP response body content. From endpoint scripts, Lua Table are transformed to the equivalent JSON structure.

Example

-- In a webservice endpoint script:
response.code = 201
response.headers["x-my-custom-header"] = "my header content"
response.message = {hello = "world"} -- or return {hello = "world"}

-- Same behavior in EventHandler script:
function handle_webservice_request (request)

  return {
    code = 201,
    message = "{\"hello\":\"world\"}",
    headers = { ["content-type"] = "application/json" }
  }

end

Name	Type	Description
domain	^[a-zA-Z0-9-]{1,63}\(\\\.\[a-zA-Z0-9-\]\{1,63\}\)*$	The public domain name used for the API. IMPORTANT: Only last subdomain can be changed. To use a custom domain, contact Exosite support.
cors	object	Restrictions on how the API should be accessed by client websites to increase navigation security. Find more about CORS on https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
cors.origin	[ ^\(\\\\|\(\[a-z\]\+:\\/\\/\(\\\?\|\[a-zA-Z0-9-\]\+\)\(\\\.\[a-zA-Z0-9-\]\+\)?\(:\(\\\\|\[0-9\]\+\))?))$ ]	List of allowed domains. Default: []
cors.headers	[ string ]	Set Access-Control-Allow-Headers header value
cors.methods	[ "HEAD", "GET", "PUT", "POST", "DELETE", "PATCH", "OPTIONS" ]	Set Access-Control-Allow-Methods header value
cors.credentials	boolean	Set Access-Control-Allow-Credentials header value
cors.expose_headers	[ string ]	Set Access-Control-Expose-Headers header value
headers	object	Http headers
headers.^[\w-]{1,200}$	string	Header value
documented_endpoints	[ string {..40} ] {..10}	List of tags used to filter which endpoints to expose to public documentation.
security_schemes	[ object ]	The security schemes supported by the API. You need to specify in the 'security' parameter which scheme to use for which endpoints. Default: []
security_schemes[].in	"header", "query", "cookie"	For `type=apiKey` only, the place to put token.
security_schemes[].name	string	For `type=apiKey` only. The name of parameter or header to find the apiKey.
security_schemes[].type	"bearer", "basic", "apiKey"	The authentication type. It could be `basic`, `bearer`, `apiKey` etc.
security	[ "none", "basic", "bearer", "apiKey" ]	The authentication method for all endpoints. Select from the security schemes. Default: []
rate_limit	integer	Request rate limit per token per minute. Default is 0, meaning no limit.
api_info	object	Info for the auto-generated swagger API.
api_info.title	string	Title of your solution API.
api_info.contact	object	Contact info of your solution API.
api_info.contact.name	string	Your name
api_info.contact.email	string(email)	Your email
api_info.version	string	Version of your solution API. Default: "v1"
api_info.description	string	A description of your solution API.

Name	Type	Description
code	string	Response code
type	string	Error type
message	string	Error message

Name	Type	Description
path	string	API path to retrieve the file
checksum	string	File checksum
mime_type	string	File mime type