REST API: Meta information and versioning

This topic describes the Meta information tab of a REST API definition and the supported versioning approaches. For an overview of the REST API configuration, see REST API.

Meta-information tab

In the Meta information tab, you record informative details about the REST API. These details appear in the OpenAPI documentation depending on the call context.

The platform stores the information in the meta field of the REST API class (RestApi). The field contains a RestApiMetadata data object with the following structure:

Property	Data type	Data field (path)	Notes
Info	`RestApiMetadata`	`(meta)`
Title	`String`	`title`
Version	`String`	`version`	Typical format: `<major>.<minor>.<patch>`. Purely informational. For details, see the "API versioning" section.
Summary	`String`	`summary`
Description	`String`	`description`
Terms of service	`String`	`termsOfService`
Contact	`RestApiMetadata$Contact`	`contact`	The data field path refers to the `RestApiMetadata` object in the `meta` field.
Contact > Name	`String`	`contact.name`
Contact > URL	`String`	`contact.url`
Contact > Email	`String`	`contact.email`
License	`RestApiMetadata$License`	`license`	The data field path refers to the `RestApiMetadata` object in the `meta` field.
License > Name	`String`	`license.name`
License > URL	`String`	`license.url`
License > Identifier	`String`	`license.identifier`

API versioning

As soon as you publish server-side functions via an API, the question of versioning arises. The REST API configuration supports multiple approaches.

Version in the base URI

The base URI property (baseUri) can contain a static version number. It is common to prefix the version number with the letter v. Example: v2/lookup within an endpoint URL such as ./api/v2/lookup/item/4711.

Version in the endpoint URI

You can also place a version indicator within the URI property (uri) of an endpoint. Example: v2/getItem/{id} within an endpoint URL such as ./api/lookup/v2/getItem/4711.

Version as URI parameter

Within the URI, you also map the version number to a variable. Example: v{version}/getItem{id} for the endpoint URL ./api/lookup/v2/getItem/4711. The action block then distinguishes cases via the version variable, for example, with If then else or Conditional value.

Version as query parameter

Alternatively, place the version index as a query parameter. In the action block, you access it via the queryParameters map. Example: ./api/lookup/getItem/4711?v=2.

Version as request header

You can also pass a version identifier into the action block via the requestHeaders map as a header parameter. The version then does not appear in the URL but is still accessible in the action block.

NOTE The platform uses the version field in the Meta information tab purely informatively for the OpenAPI documentation. The version shown there may be misleading when multiple active REST API definitions refer to the same base URI.

Documentation Index