Version access modes

Specify how clients access service versions in REST operations.

A web service information record may include the WSVersionMode attribute, which defines how clients access versioned operations. The mode applies to all operations in the REST service.

The available version modes are:

  • uri
  • header
  • query

In this example, WSVersionMode is set to "query", which applies the mode to the entire service: 

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

Default version mode (URI)

If WSVersionMode is not set, or set to "uri", GWS adds the version directly to the resource path.

The OpenAPI document reflects this by prefixing the resource path with the version.

The following figures show examples for a service with one resource and for a service with multiple resources.

Figure: Version mode uri ( service with one resource)

OpenAPI JSON description of a service with one resource using uri to set version mode.
Figure: Version mode uri (service with many resources)

OpenAPI JSON description of a service with many resources using uri to set version mode.

Query mode

If WSVersionMode is set to "query", GWS adds the api-version query parameter to the OpenAPI description.

  • The client must send the required version using this query parameter.
  • The OpenAPI document includes the parameter definition using the enum keyword.

  • GWS appends the query string automatically in requests, for example: ?api-version=v3

Figure: Version mode query

OpenAPI JSON description of a service using a query to set version mode.

Header mode

If WSVersionMode is set to "header", GWS adds the api-version HTTP header parameter to the OpenAPI description.

  • The client must include this header in each request.
  • The OpenAPI document includes the header definition using the enum keyword.
Figure: Version mode header

OpenAPI JSON description of a service using a header to set version mode.