Advanced REST API versioning

Versioning an operation

Assign a version name to an operation using the WSVersion (function) attribute (for example, WSVersion="v2"). This allows multiple versions of the same path and HTTP verb to coexist.

Example:

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

For details, go to Operation-level versioning

Versioning a service

You can assign a version to the entire service by setting WSVersion in the information record. All operations inherit this version unless they define their own WSVersion.

Service-level versioning is useful when most operations change together or when introducing a major version.

For details, go to Service-level versioning.

Default service version for OpenAPI

You can define a default version for the OpenAPI documentation. Set the version name in the WSVersion (module) attribute of the information record.

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

For details, go to Set the default service version for OpenAPI documentation.

Versioning mode

Choose how clients specify a version using the WSVersionMode attribute in the information record. Supported methods include using the URI, a custom header, or a query string parameter.

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

For details, go to Version access modes.

Read the topics in this section for details about the versioning features provided by the Genero Web Services, including operation-level versioning, service-level versioning, default versions, and version-access modes.

If you’re new to versioning, the following topics are a good starting point:

• Create a new version of an operation
• Set a default version of an operation
• Service-level versioning