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