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. 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 |
:/?#[]@!$&'()*+,;=
), 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