Skip to content

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} ] 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} ] 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} ] 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} ] 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} ] 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

Last update: December 7, 2021
Back to top