REST API Gateway Service

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. Read more on the https://docs.exosite.com/development/quickstart/ 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

Cors
Endpoint
File
Other

Events


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 {..5000} 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

Retrieve the API cross-origin HTTP request policy settings.

Responses

Cross-origin HTTP request policy

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

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
Failed to retrieve schema

Content: object Error response

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 [ ^(\*|([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

CORS settings updated

Content: nil

Failed to retrieve schema

Content: object Error response

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

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]+}))*(\/(\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

Endpoint information

Content: object

Name Type Description
id string Endpoint Id
Failed to create endpoint

Content: object Error response

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

Content: nil

Failed to delete endpoint

Content: object Error response

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

Endpoint retrieved

Content: object An API endpoint definition.

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.
Failed to retrieve endpoint

Content: object Error response

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/

Content: object

Name Type Description
Failed to retrieve schema

Content: object Error response

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.

Content: [ 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.
Failed to retrieve endpoint list

Content: object Error response

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]+}))*(\/(\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

Endpoint updated

Content: nil

Failed to update endpoint

Content: object Error response

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

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

Content: nil

Failed to delete file

Content: object Error response

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

headFile

As get the file but don't 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

Content: nil

Failed to access file

Content: object Error response

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.

Content: [ object ]

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

Content: object Error response

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

updateFile

Update file metadata

Arguments

parameters - object - Object containing service call parameters.
Name Type Description
file string The API path where file is located
path string API endpoint to access the file.

Responses

File updated

Content: nil

Failed to update file

Content: object Error response

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

Other

(deprecated) apiReply

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

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 {100..600} 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

Response successfully sent

Content: nil

Fail to send the HTTP response. More information is available in the operation response.

Content: object Error response

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

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

Response content to the http request.

Content: object The request response data to reply to the client.

Name Type Description
code integer {100..600} 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