REST Host

The RESTHost allows you to assemble and publish a REST web service endpoint by implementing its web methods through events. This can be done using a Swagger API description file, which imports one event for each path defined in the file.

Note:

  • RESTHost supports OpenAPI 3.0.

  • Previously built solutions using Swagger 2.0.x definitions will continue to function as expected. However, new solutions will only support OpenAPI 3.0.

  • If you copy a Swagger 2.0.x API service definition from an existing solution into a new solution, it will not work. You must convert a Swagger 2.0.x definition to OpenAPI 3.0 before adding it to a Linx solution. For help with conversion, see Swagger.

Need help creating an API definition?

Use the Linx OpenAPI3 Definition Designer to create a valid OpenAPI 3 definition. Once created, add it to the RESTHost function's API definition property as described below.


Properties

API definition

A valid OpenAPI 3 definition for your web API in JSON or YAML format. Ensure that it is valid according to the OpenAPI 3 specification before adding it to the API Definition Editor. You can validate your definition online at Swagger Hub.

Exceptions

The following aspects of the OpenAPI 3 specification 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

Configure the base URL of the web service to be hosted on the server where it is deployed.

In Linx, use the + wildcard character instead of your hostname in the Base URL property:

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

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. These settings are automatically pulled into the Auth config editor, from which you can update them.

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.

Last updated