WSVersion (module)

Set a default set of operations to display in the OpenAPI documentation.

Syntax

WSVersion = "{ version }"
Where:
  1. 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 using WSVersion at the module level, be aware that it can only contain one value, and the value must not be called "default". Setting more than one version or setting WSVersion ="default" is only allowed with WSVersion(Function), but causes compilation error-9140 to be thrown when detected at the module level.

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.
There are considerations for setting a default version for the OpenAPI document. The version selected must make up a complete set of operations for the Web service to include:
  • operations whose version name matches the version name set in the WSVersion of REST functions.
    Tip:

    First version

    It is possible to use a version name which is not used in any operation. This new version will only display operations without WSVersion or with WSVersion="default". This option is useful if you want to use versioning in the first release of your Web service (for example, WSVersion="v1"), where, in fact, no operation has been versioned. It will introduce clients to the concept of version control in your Web service.

  • operations with a default version. These are operations which are general to all versions as they either do not have a WSVersion set in the function or are set with WSVersion=default.

To learn more setting a default version of operations, see Default version of the OpenAPI document.

Example using WSVersion in the information record

In the example, the WSVersion is set to "v3". This defines version v3 as the default version of operations displayed in the OpenAPI documentation of 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") )