WSVersion (module)

Sets the version of the REST service for OpenAPI documentation.

Syntax

WSVersion = "{ version }"

Where:

version is a string value setting the version of the Web service.

WSVersion is an optional attribute.

Usage

You use this attribute to specify version at the module level. It activates versioning for the web service. 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.

Set a version name on the WSVersion attribute in the service information record of the module. By doing this you specify the version of operations of the web service that are displayed in the OpenAPI document and in the generated stub file.

Warning:

When you use WSVersion at the module level, you can only assign a single version, and the value cannot be "default". Multiple versions or using WSVersion="default" are only allowed at the function level. If either is detected at the module level, the compiler reports error error-9140.

OpenAPI

When a default version is defined for a service, you do not need to specify the version in the query string when requesting the OpenAPI document. For example, the following request returns the OpenAPI documentation for the default version of the service: http://myServer:myPort/gas/ws/r/myGroup/myXcf/myService?openapi.json

Important:

Setting a default version is optional. However, if no default version is defined and the client does not specify a version in the query string, the request returns a 404 (Not found) and the server raises error 41 internally.

The output shown in this example is from the Firefox™ browser, which formats JSON for readability. The appearance may vary depending on your browser.

When choosing a default version for the OpenAPI document, make sure the version represents a complete set of operations for the service. The default version can include:

operations whose WSVersion value matches the version name you set at the module level, and
operations that are unversioned or use WSVersion="default".

You can also choose a version name that is not used by any operation. In this case, the OpenAPI document only includes operations without WSVersion or with WSVersion="default". This is useful when introducing versioning in the first release of a service; for example, setting WSVersion="v1" even though none of the operations are versioned yet. It helps users understand that versioning is supported and prepares them for future changes.

To learn more setting a default version of operations, see Set the default service version for OpenAPI documentation.

Example using WSVersion in the information record

In the example, the WSVersion is set to "v3". This makes v3 the default version used when generating the OpenAPI documentation for the web service.

The main purpose of the service information record (defined with the WSInfo attribute) is to document the REST service. If you are not setting the version at the modular level here, the record is still needed to provide service information.

PUBLIC DEFINE serviceInfo RECORD ATTRIBUTES(WSInfo, WSScope="users", WSVersion="v3")
  title STRING,
  description STRING,
  termOfService STRING,
  contact RECORD
    name STRING,
    url STRING,
    email STRING
    END RECORD,
    version STRING
  END RECORD = (
    title: "my service", 
    version: "1.0", 
    contact: ( email:"helpdesk@mysite.com") )