WSVersion (function)

Specify version in the REST service via a version name.

Syntax

WSVersion = "{ version } [,...]"
Where WSVersion is a comma-separated list of versions and where:
  1. version defines the version of the operation.

WSVersion is an optional attribute.

Usage

You use this attribute to specify version at the function level. It activates versioning for the Web service. When the GWS detects the WSVersion attribute, it automatically switches to versioning mode. This affects how it generates the OpenAPI documentation and ultimately how resources are accessed. You must now add the query "&version=nameVersion" in the URI to get the OpenAPI documentation. For example: http://myhost:6394/ws/r/myservice?openapi.json&version=v2.

Set a version name on the WSVersion attribute in the ATTRIBUTES() clause of the REST function. By doing this you specify the version of the Web service in which the operation will be accessible to clients.

You can use this attribute to update a previous version of the same operation (with the same path and verb) to a new version of the operation. Existing versions are not affected and can still be used.

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.

Important:

Setting a default version is optional but if not specified, and you do not request a version in the query string of the URI to generate the OpenAPI documentation, the client will get a 404 (Not found) error response and internally the server will throw error 41.

When an operation is accessible in one or more versions, you can set these specifically within the attribute, for example, WSVersion="v1,v2,v3".

You can display the documentation for a specific version of the Web service, by adding the query "&version=nameVersion" in the URI. For example: http://myhost:6394/ws/r/fruits?openapi.json&version=v2

You can specify the version of operations of the Web service that are displayed in the OpenAPI document and in the generated stub file by setting WSVersion in the service information record of the module. For more information on specifying the default version of operations of the Web service, see WSVersion (module).

Example setting WSVersion in functions

In the example, the function "prices_default" is set as the default version of the prices operation. There are two different versions of operations defined for the Web service, "v2" and "v3".

When you generate the OpenAPI documentation for version 3, for example, http://myhost:6394/gas/ws/r/myGroup/myXcf/myService?openapi.json&version=v3, the GWS will select the "prices_default" operation in v3.

In requests for version 2, as a version of the function is available, the GWS will select the "prices_v2" operation.

IMPORT com

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

TYPE priceType RECORD
  item VARCHAR(150),
  unit_measure VARCHAR(150),
  price DECIMAL(10,2)
END RECORD

PUBLIC FUNCTION prices_default(nb INTEGER ATTRIBUTE(WSParam))
  ATTRIBUTES (WSGet,WSPath = "/prices/{nb}",
               WSDescription = "Returns the price of an item",
               WSThrows = "404:item not found",
               WSVersion = "default")
  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
PUBLIC FUNCTION quantity_v3(id INTEGER ATTRIBUTE(WSParam) )
 ATTRIBUTES (WSGet,WSPath = "/quantity/{id}",
              WSDescription = "Returns an item quantity for API v3",
              WSThrows = "404:item not found",
              WSVersion = "v3")
 RETURNS (INTEGER)
   DEFINE quantity INTEGER
   
     TRY
      SELECT qty INTO quantity FROM inventory
        WHERE itemid = id
      IF sqlca.sqlcode == NOTFOUND 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(400,userError)
    END TRY
  RETURN quantity
 END FUNCTION
PUBLIC FUNCTION prices_v2(nb INTEGER ATTRIBUTE(WSParam))
  ATTRIBUTES (WSGet,WSPath = "/prices/{nb}",
               WSDescription = "Returns price details for an item for API v2",
               WSThrows = "404:item not found",
               WSVersion = "v2")
  RETURNS (priceType)
    DEFINE price priceType
    TRY
      SELECT unit_title, measure_unit, unit_price INTO price.*
        FROM unit_pricing
        INNER JOIN measure_type
        ON unit_pricing.measure_typeid = measure_type.measure_id
        WHERE unit_pricing.unit_id = nb

      IF sqlca.sqlcode == NOTFOUND 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