RESTHost

Assemble and publish a REST web service endpoint by implementing its web methods through events using RESTHost. The definition for the web service is imported through a Swagger API description file. The API description import creates one event for each path defined in the Swagger file.

Note:

  • RESTHost supports OpenAPI 3.0.

  • Solutions that were previously built to work with Swagger 2.0.x definitions will continue to work as expected, but in the case of new solutions, RESTHost will only support OpenAPI 3.0.

  • Thus, if a user copies the Swagger 2.0.x API service definition from a working solution into a new solution, the definition will not work. A Swagger 2.0.x definition must first be converted to an OpenAPI 3.0 definition before adding it a Linx solution. See Swagger for help on converting from Swagger 2.0 to OpenAPI 3.0.

Need help creating an API definition?

Use the Linx OpenAPI3 Definition Designer to create a valid Open API 3 definition. After creating your definition, add it to the RESTHost function's API definition property, as described below.

Properties

API definition

A valid Open API 3 definition for your web API, in JSON or YAML format. Before adding your API definition in the API Definition Editor, ensure that it is valid as per the Open API 3 specification. Validation can be done online at Swagger Hub.

Exceptions

Aspects of the Open API 3 specification which are not supported by the RESTHost:

  • Variant type definitions, for example:
    • empty schema definitions
    • objects with empty "properties" lists

  • Polymorphism:
    • oneOf
    • anyOf
    • allOf
    • discriminator
  • Content type wildcards


Base URI

The Base Url of the web service must be configured to be hosted on the server that it is deployed to.

To achieve this in Linx, use the + wildcard character instead of your hostname in the Base Url property.

https://+:{port}/{path}

Base URI

When the service is deployed it will use the current server.

Auth config

Authentication configuration can be defined in the security schemas of the API description. Those settings are automatically pulled into the Auth config editor, from where it can be updated.

If no authentication settings were added in the API description or if additional authentication settings are required, it can be added in the editor.

AuthConfig

To add an item or field's associated detail, click the Editor icon.

Return server errors

Show details for internal server errors in HTTP responses.

Values: true / false

Max connections

The maximum number of concurrent connections to accept (per client).

Max request size

The maximum allowed size of any request body, in megabytes.

Default: 30

API documentation

Select to generate documentation for your API.

Options:

  • Redocly

  • Swagger UI

To access your generated documentation, append /swagger or /redocly to your Base URI, depending on the documentation type.

For more on API documentation go here.

CORS origins

A list of allowed origin URLs for cross-origin resource sharing.

Click the editor icon to add relevant URLs.

Authenticate

Select to show the Authenticate event handler.

This handler will execute for every authentication scheme associated with an operation, before the execution of the operation.

Before operation

Select to show the Before-Operation event handler.

This handler will execute before the execution of any operation.

After operation

Select to show the After-Operation event handler.

This handler will execute after the execution of any operation.


Note:

In case your output does not display as expected when using the default response, use an explicit response code (e.g. 404).

For more on response handling, go here.


OpenAPI Specification

Wikipedia: Representation state transfer (REST)

Swagger

All WCF timeouts explained

RESTHost Overview Guide

Get Started - Hello World

Before and After operation events

Working with inputs

Handling responses

Securing your API

Deploying and common issues

Generating API documentation

Sample solution: CRUD and file operations

Cloud server API deployment