Custom API Gateway Service

Enabled web-based, HTTPS-encrypted access to your solution's endpoints and assets.

Endpoint scripts are developed within your application Endpoints tab or can be deployed from the Murano CLI tool.

Each request reaching your API endpoints will trigger the execution of the deployed scripts. This service provides automatically the API definition in an (openapi v2.0)[https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md] format from a default '/swagger.json' & '/swagger.yaml' endpoint.

Operations

Cors

Endpoint

File

Webservice_response

Events

Operations

Cors


getCors

Retrieve the API cross-origin HTTP request policy settings.

Responses

CORS settings retrieved

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

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

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 receive 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 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]+}))*\/?$ 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 receive 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 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]+}))*\/?$ 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 receive 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 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]+}))*\/?$ 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 receive 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 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

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

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

Webservice_response


(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", "OPTION" 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.message = {hello = "world"} response.headers["x-my-custom-header"] = "my header content"
-- Same behavior in EventHandler script:
function handle_webservice_request (request)

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

end