Versioning with URI

You can version a resource using the WSPath attribute. The version is included in the resource URI.

In effect it means that you have two versions of the API and are able to generate a different openapi.json description per version based on the path of your REST API.

For example, before versioning a resource was at:

http://myhost:6394/gas/ws/r/myGroup/myXcf/resource

After versioning the resource is now at:

http://myhost:6394/gas/ws/r/myGroup/myXcf/myVersion/resource

Even though this in principle breaks the constraint that the URI should refer to a unique resource, it is the preferred way.

Example setting version in the path

This example assumes changes to the profile record type (profileType2) that are not compatible with the previous version of the API. The WSPath to the new function now contains a version number (v2) that provides the path to the resource.

IMPORT com

TYPE profileType2 RECORD ... END RECORD

PUBLIC FUNCTION FetchMyUser2Profile(p_user_id INTEGER ATTRIBUTE(WSParam) )
  ATTRIBUTES(
    WSGet,
    WSPath="/users/v2/{p_user_id}",
    WSDescription="Returns a user profile for API v2 ",
    WSThrows="404:user not found"
    )
  RETURNS profileType2 ATTRIBUTES(WSName="data",
                                 WSMedia="application/json,application/xml")
    DEFINE p profileType2
    WHENEVER ERROR CONTINUE
    SELECT * INTO p.* FROM users
             WHERE user_id == p_user_id
    WHENEVER ERROR STOP
    IF sqlca.sqlcode==NOTFOUND THEN
        INITIALIZE p TO NULL
        CALL com.WebServiceEngine.SetRestError(404,NULL)
    END IF
    RETURN p.*
END FUNCTION

An example of the resource URL, using the new version to retrieve the data for user 1, is:

http://myhost:6394/gas/ws/r/myGroup/myXcf/Accounts/users/v2/1