Advanced REST API versioning

The advanced REST API versioning allows you to manage multiple versions of your REST Web service with minimal coding.

To activate REST API versioning, you set the WSVersion attribute on a function or at the module level in the service information record (WSInfo attribute). When the GWS detects the WSVersion attribute, it automatically switches to versioning mode. This affects how it generates the OpenAPI documentation and ultimately how resources are accessed. The following sections detail how you implement versioning.

Versioning an operation

When you need to provide a new version of an operation, a version indicator (such as a name) needs to be added in the WSVersion (function) attribute. You identify the version with a unique value, for example, WSVersion="v2". For more information on version naming, see How to name versions.

For example, the function in the sample is versioned:

PUBLIC FUNCTION prices_v2(nb INTEGER ATTRIBUTES(WSParam)) 
  ATTRIBUTES (WSGet,WSPath="/prices/{nb}", WSVersion="v2")
  RETURNS (INTEGER)
  # function code ... 
END FUNCTION

When an operation is accessible in one or more versions, you can set these specifically within the attribute, for example, WSVersion="v1,v2,v3".

The GWS allows you to use the same operation (same path and HTTP verb) multiple times provided you use a different version in each. An operation that does not contain a WSVersion attribute or has WSVersion="default" will be used in all versions.

To learn about versioning operations, see Version an operation, Version an operation as default, and Version an operation with multiple versions.

Versioning the OpenAPI documentation with default

It is possible to specify a default version of operations to automatically display in the OpenAPI documentation. You set this in the WSVersion (module) attribute in the service information record.

PUBLIC DEFINE myInfo RECORD ATTRIBUTES(WSInfo, WSVersion = "v3")
   title STRING
   # ...
END RECORD

OpenAPI

With a default version, there is no need to specify the version in the query string in the URI to generate the OpenAPI documentation. For example, with a standard URI request for JSON output, http://myServer:myPort/gas/ws/r/myGroup/myXcf/myService?openapi.json, the GWS generates documentation for the version of operations set as default.

Important:

Setting a default version is optional but if not specified, and you do not request a version in the query string of the URI to generate the OpenAPI documentation, the client will get a 404 (Not found) error response and internally the server will throw error 41.

The output shown is from the Firefox® browser, which converts JSON to human readable format. The output may vary depending on your browser.

To learn about versioning the OpenAPI document, see Default version of the OpenAPI document.

Versioning mode

WSVersion function and module attributes activate versioning mode. In the default versioning mode, the GWS automatically prefixes the version to the operation's resource path in the OpenAPI documentation. This is the uri versioning mode.

For example, if before versioning, the resource path as defined by WSPath was:

/prices/{nb}

After versioning the operation (the version is set as "v2"), the resource path is:

/v2/prices/{nb}

Access to operations can be changed with the optional attribute WSVersionMode on the service information record.

PUBLIC DEFINE myInfo RECORD ATTRIBUTES(WSInfo, WSVersion = "v3", WSVersionMode="query")
   title STRING
   # ...
END RECORD

You can set the versioning mode to one of the three supported versioning methods; versioning the URI, adding a custom header, or using a query string, depending on your preference. The whole REST Web service will use the chosen mode.

To learn about version mode (to include how the GWS handles version mode in the OpenAPI description of operations ), see Specify version mode.