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
Quickstartguilde of the West Connectivity platform documentation page. 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
- (deprecated) Webservice.getCors() - Get the API CORS
- (deprecated) Webservice.setCors() - Set the API CORS
Endpoint
- Webservice.createEndpoint() - Create endpoint
- Webservice.deleteEndpoint() - Delete endpoint
- Webservice.getEndpoint() - Get an endpoint
- Webservice.getSwagger() - Get the Swagger schema
- Webservice.listEndpoints() - List the endpoints
- Webservice.updateEndpoint() - Update endpoint
File
- Webservice.deleteFile() - Delete a file
- Webservice.listFiles() - List API static files
- Webservice.updateFile()
Other
- (deprecated) Webservice.apiReply() - Reply to API request
Events
- request - HTTP request
Configuration parameters
Please note that bold arguments are required, while italic arguments are optional.
| 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 West Connectivity 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", "mobileApp" | The authentication type. It could be basic, bearer, apiKey, mobileApp etc. |
| security | [ "none", "basic", "bearer", "apiKey", "mobileApp" ] | The authentication method for all endpoints. Select from the security schemes. When using mobileApp which expect valid JWT, provide header x-mobile with value <"apple"OR"google">" " Default: [] |
| rate_limit | integer | Request rate limit per token per minute. 0 means no limit. Default: 1200 |
| 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
Please note that bold arguments are required, while italic arguments are optional.
(deprecated) getCors
Retrieve the API cross-origin HTTP request policy settings.
SRS-ID: S-WEBSERVICE-INT-003
Responses
| Code | Body Type | Description |
|---|---|---|
| 200 | object | Cross-origin HTTP request policy |
| default | object | Failed to retrieve schema |
Object Parameter of 200 response:
| 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 |
Object Parameter of default response:
| Name | Type | Description |
|---|---|---|
| code | string | Response code |
| type | string | Error type |
| message | string | Error message |
(deprecated) setCors
Set the API cross-origin HTTP request policy settings.
SRS-ID: S-WEBSERVICE-INT-003
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
| Code | Body Type | Description |
|---|---|---|
| 204 | nil | CORS settings updated |
| default | object | Failed to retrieve schema |
Object Parameter of default response:
| Name | Type | Description |
|---|---|---|
| code | string | Response code |
| type | string | Error type |
| message | string | Error message |
createEndpoint
Create an API endpoint.
SRS-ID: S-WEBSERVICE-INT-002
Arguments
parameters (object) - Object containing service call parameters.
| Name | Type | Description |
|---|---|---|
| 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. |
| summary | string | Summary of endpoint |
| security | [ "none", "basic", "bearer", "apiKey", "mobileApp" ] | The authentication method for all endpoints. Select from the security schemes. When using mobileApp which expect valid JWT, provide header x-mobile with value <"apple"OR"google">" " 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. |
| rate_limit | integer | Request rate limit per token per minute. 0 means no limit. |
| description | string | Description of endpoint |
| 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" |
Responses
| Code | Body Type | Description |
|---|---|---|
| 200 | object | Endpoint information |
| default | object | Failed to create endpoint |
Object Parameter of 200 response:
| Name | Type | Description |
|---|---|---|
| id | string | Endpoint Id |
Object Parameter of default response:
| Name | Type | Description |
|---|---|---|
| code | string | Response code |
| type | string | Error type |
| message | string | Error message |
deleteEndpoint
Delete an API endpoint.
SRS-ID: S-WEBSERVICE-INT-002
Arguments
parameters (object) - Object containing service call parameters.
| Name | Type | Description |
|---|---|---|
| endpoint_id | string | The endpoint Id |
Responses
| Code | Body Type | Description |
|---|---|---|
| 204 | nil | Endpoint deleted |
| default | object | Failed to delete endpoint |
Object Parameter of default response:
| Name | Type | Description |
|---|---|---|
| code | string | Response code |
| type | string | Error type |
| message | string | Error message |
getEndpoint
Retrieve an API endpoint information.
SRS-ID: S-WEBSERVICE-INT-002
Arguments
parameters (object) - Object containing service call parameters.
| Name | Type | Description |
|---|---|---|
| endpoint_id | string | The endpoint Id |
Responses
| Code | Body Type | Description |
|---|---|---|
| 200 | object | Endpoint retrieved |
| default | object | Failed to retrieve endpoint |
Object Parameter of 200 response:
| Name | Type | Description |
|---|---|---|
| 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. |
| summary | string | Summary of endpoint |
| security | [ "none", "basic", "bearer", "apiKey", "mobileApp" ] | The authentication method for all endpoints. Select from the security schemes. When using mobileApp which expect valid JWT, provide header x-mobile with value <"apple"OR"google">" " 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. |
| rate_limit | integer | Request rate limit per token per minute. 0 means no limit. |
| description | string | Description of endpoint |
| 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" |
Object Parameter of default response:
| Name | Type | Description |
|---|---|---|
| code | string | Response code |
| type | string | Error type |
| message | string | Error message |
getSwagger
Retrieve the API Swagger schema.
SRS-ID: S-WEBSERVICE-INT-002
Responses
| Code | Body Type | Description |
|---|---|---|
| 200 | object | Swagger schema as defined by http://swagger.io/specification/ |
| default | object | Failed to retrieve schema |
Object Parameter of 200 response:
| Name | Type | Description |
|---|---|---|
Object Parameter of default response:
| Name | Type | Description |
|---|---|---|
| code | string | Response code |
| type | string | Error type |
| message | string | Error message |
listEndpoints
Retrieve the list of the API endpoints.
SRS-ID: S-WEBSERVICE-INT-002
Responses
| Code | Body Type | Description |
|---|---|---|
| 200 | [ object ] | Endpoints list. |
| default | object | Failed to retrieve endpoint list |
Object Parameter of 200 response:
| Name | Type | Description |
|---|---|---|
| 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. |
| summary | string | Summary of endpoint |
| security | [ "none", "basic", "bearer", "apiKey", "mobileApp" ] | The authentication method for all endpoints. Select from the security schemes. When using mobileApp which expect valid JWT, provide header x-mobile with value <"apple"OR"google">" " 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. |
| rate_limit | integer | Request rate limit per token per minute. 0 means no limit. |
| description | string | Description of endpoint |
| 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" |
Object Parameter of default response:
| Name | Type | Description |
|---|---|---|
| code | string | Response code |
| type | string | Error type |
| message | string | Error message |
updateEndpoint
Update an API endpoint.
SRS-ID: S-WEBSERVICE-INT-002
Arguments
parameters (object) - Object containing service call parameters.
| Name | Type | Description |
|---|---|---|
| endpoint_id | string | The endpoint Id |
| 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. |
| summary | string | Summary of endpoint |
| security | [ "none", "basic", "bearer", "apiKey", "mobileApp" ] | The authentication method for all endpoints. Select from the security schemes. When using mobileApp which expect valid JWT, provide header x-mobile with value <"apple"OR"google">" " 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. |
| rate_limit | integer | Request rate limit per token per minute. 0 means no limit. |
| description | string | Description of endpoint |
| 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" |
Responses
| Code | Body Type | Description |
|---|---|---|
| 204 | nil | Endpoint updated |
| default | object | Failed to update endpoint |
Object Parameter of default response:
| Name | Type | Description |
|---|---|---|
| code | string | Response code |
| type | string | Error type |
| message | string | Error message |
deleteFile
Remove the static file.
SRS-ID: S-WEBSERVICE-INT-004
Arguments
parameters (object) - Object containing service call parameters.
| Name | Type | Description |
|---|---|---|
| path | string | The API path where file is located |
Responses
| Code | Body Type | Description |
|---|---|---|
| 204 | nil | Files deleted successfully |
| default | object | Failed to delete file |
Object Parameter of default response:
| Name | Type | Description |
|---|---|---|
| code | string | Response code |
| type | string | Error type |
| message | string | Error message |
listFiles
Retrieve the list of static files.
SRS-ID: S-WEBSERVICE-INT-004
Responses
| Code | Body Type | Description |
|---|---|---|
| 200 | [ object ] | Files list. |
| default | object | Failed to retrieve file list |
Object Parameter of 200 response:
| Name | Type | Description |
|---|---|---|
| path | string | API path to retrieve the file |
| checksum | string | File checksum |
| mime_type | string | File mime type |
Object Parameter of default response:
| Name | Type | Description |
|---|---|---|
| code | string | Response code |
| type | string | Error type |
| message | string | Error message |
updateFile
Update file metadata
SRS-ID: S-WEBSERVICE-INT-004
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
| Code | Body Type | Description |
|---|---|---|
| 204 | nil | File updated |
| default | object | Failed to update file |
Object Parameter of default response:
| Name | Type | Description |
|---|---|---|
| code | string | Response code |
| type | string | Error type |
| message | string | Error message |
(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 West Connectivity endpoint script, you DO NOT need to use this operation manually as the West Connectivity 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 West Connectivity endpoint script. |
| code | integer | The HTTP response status code Maximum: 600 Minimum: 100 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
| Code | Body Type | Description |
|---|---|---|
| 204 | nil | Response successfully sent |
| default | object | Fail to send the HTTP response. More information is available in the operation response. |
Object Parameter of default 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, West Connectivity 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 West Connectivity 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. |
| method | "POST", "PUT", "GET", "DELETE", "PATCH", "WEBSOCKET" | The HTTP method of the request, matching the custom API endpoint configuration. |
| 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 in the endpoint path by using brackets. Eg. '/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
| Code | Body Type | Description |
|---|---|---|
| default | object | Response content to the http request. |
Object Parameter of default response:
| Name | Type | Description |
|---|---|---|
| code | integer | The HTTP response status code Maximum: 600 Minimum: 100 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
Service Health Check
Operations
/api/v1/solution/health
Enable the hosting system to check if service is active and running
SRS-ID: S-WEBSOCKET-INT-004
Arguments
No Content
Responses
| Name | Type | Description |
|---|---|---|
| 200 | string | OK |
Errors
No content