WSParam

Specifies a value for a template path to a REST Web service resource.

Syntax

WSParam

WSParam is an optional attribute.

Usage

You use this attribute for path templating to specify values that are provided at runtime in function parameters. You set the WSParam attribute in the ATTRIBUTES() clause of the parameter.

For each Genero BDL function parameter with a WSParam attribute, there must be a matching template path in the WSPath. fglcomp checks to ensure that there is one template value per parameter, otherwise compilation error-9111 is thrown.

You can set the WSParam attribute on parameters defined as records and arrays. The GWS and fglrestful supports serialization and deserialization of path parameters according to defaults set by the OpenAPI specification.

WSParam supports the default style: simple and explode: false. Table 1 shows how the path (users) is serialized when the parameter (id) is a primitive type, an array, or a record. For further information on OpenAPI serialization, see the Parameter serialization page.

Table 1. OpenAPI path parameters and serialization
style	explode	Primitive value id = 5	Array id = [3, 4, 5]	Record = {"role": "admin", "lastName": "Smith"}
simple	false	/users/5	/users/3,4,5	/users/role,admin,lastName,Smith

If a value contains special characters as defined by RFC3986 (for example, :/?#[]@!$&'()*+,;=), the GWS engine serializes them with percent-encoding in the parameter. For example:

DEFINE b DYNAMIC ARRAY OF STRING = ["O,ne", "Two", "Three", NULL, "Five"]

The parameter contains: O%2Cne,Two,Three,,Five. The server and the client must deserialize "O%2Cne" to "O,ne" for insertion in Genero BDL.

Example path templating with WSParam

TYPE accountType RECORD ... END RECORD

PUBLIC FUNCTION getAccountById(id INTEGER ATTRIBUTE(WSParam))

  ATTRIBUTES(WSGet,
    WSPath="/accounts/{id}",
    WSDescription="Returns an account record",
    WSThrows="404:not found"
  )
  RETURNS accountType ATTRIBUTES(WSName="Account",WSMedia="application/xml") 
    DEFINE p_accountRec accountType
    # ... function code ...
    RETURN p_accountRec.*   
END FUNCTION

The client application needs to provide an appropriate parameter value when making a call to the function. For example, the variable part of the path (id) is replaced by the integer value /4 in the URL:

http://myhost:6394/gas/ws/r/myGroup/myXcf/MyService/accounts/4

Example WSParam set on parameter defined as array

TYPE userType RECORD 
   name string
   # ... 
 END RECORD
TYPE userListType DYNAMIC ARRAY OF userType
TYPE paramListType DYNAMIC ARRAY OF INTEGER

PUBLIC FUNCTION getUserById( id paramListType ATTRIBUTE(WSParam) )
  ATTRIBUTES(WSGet, WSPath="/users/{id}",
  WSDescription="Returns one or more user records",
  WSThrows="404:not found"
  )
  RETURNS DYNAMIC ARRAY ATTRIBUTES(WSName="Users") OF userType
  
  DEFINE p_userRec userType
  DEFINE p_recList userListType
  # ... function code ...
  RETURN p_recList
END FUNCTION

In the function the parameter id is an array type. The GWS deserializes the user ids sent by the client in the URL (3,4,5 in the example) for insertion into the Genero BDL parameter:

http://myhost:6394/gas/ws/r/myGroup/myXcf/MyService/users/3,4,5