Version an operation

You specify the version in which the operation will be accessible by setting the WSVersion attribute.

You version an operation if changes to an existing function, such as the request and/or response data, would break existing use of the operation. You need to create a new version of the function to apply the changes. The new version of the function will be offered with the latest release of your REST web service. This will not affect existing users who will continue to use the previous version.

If you have an operation that is static and does not change from version to version, you do not need to set a version for it, or you can set its WSVersion (function) attribute with the value "default". It will then be used by default in all versions unless the GWS finds a version of the operation when a client requests a specific version.

With versioning, you can use the same operation – with the same path and verb – as many times as needed, provided each operation has a different version value.

To create a new version of the operation:

Create a copy of the existing function, and paste it in the same file.
Rename the function copy, for example operationId_version_name.

Add the WSVersion attribute to the ATTRIBUTES clause of the function and set the version name.

For example:

IMPORT com

PUBLIC DEFINE userError RECORD ATTRIBUTES(WSError = "User error")
  message STRING
END RECORD

PUBLIC FUNCTION prices_v1(nb INTEGER ATTRIBUTES(WSParam))
  ATTRIBUTES (WSGet,WSPath = "/prices/{nb}",
               WSDescription = "Returns the price of an item",
               WSThrows = "404:item not found", 
               WSVersion = "v1") 
  RETURNS (INTEGER)
   DEFINE price DECIMAL(10,2)
    TRY
      SELECT unit_price INTO price FROM unit_pricing
        WHERE @unit_id = nb
      IF sqlca.sqlcode = 100 THEN
        CALL com.WebServiceEngine.SetRestError(404,NULL)
      END IF
    CATCH
      LET userError.message = SFMT(" - SQL error:%1 [%2]",
                                   sqlca.sqlcode, SQLERRMESSAGE)
      CALL com.WebServiceEngine.SetRestError(505,userError)
    END TRY
    RETURN price
END FUNCTION

Code the changes to the function.

To generate the OpenAPI documentation for this version, add &version=version_name to the operation query string, for example http://myhost:6394/gas/ws/r/myGroup/myXcf/myService?openapi.json&version=v1. For information about generating a version of the OpenAPI document, see Generate Open API document based on a version.