WSQuery

Specifies the query string that appears after a question mark (?) in the request URL.

Syntax

WSQuery

This attribute supports a query in the URL. Zero, one, or several parameters can be specified.

WSQuery is an optional attribute.

Usage

You set the WSQuery attribute in an ATTRIBUTE() clause of an input parameter (only) of the function. Its use is suited to filtering on resource collections. The client application needs to provide appropriate parameter values in the URL when making a call to the function, such as /users?fname=john.

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

WSQuery supports the default style: form and explode: true. 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 query parameters and serialization
style explode Primitive value id = 5 Array id = [3, 4, 5] Record = {"role": "admin", "lastName": "Smith"}
form true /users?id=5 /users?id=3&id=4&id=5 /users?role=admin&lastName=Smith

If you do not need to query each field in the record, you can add WSOptional. In this case all the fields will be optional. For an example, see Example WSQuery set as optional on a parameter defined as record.

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 WSQuery set as optional on parameters

TYPE accountType RECORD
       id VARCHAR(10),
       fname VARCHAR(25),
       lname VARCHAR(25)
       # ...
    END RECORD
    
PUBLIC FUNCTION getAccountRecords(
    resourceId VARCHAR(10) ATTRIBUTES(WSQuery, WSOptional, WSName = "id"),
    firstName VARCHAR(25) ATTRIBUTES(WSQuery, WSOptional, WSName = "fname"),
    lastName VARCHAR(25) ATTRIBUTES(WSQuery, WSOptional, WSName = "lname"))
  ATTRIBUTES (WSGet, 
              WSPath = "/accounts",
              WSDescription = "Fetches the accounts resource with the optional filter value(s) applied.",
        WSScope = "officestore.user",
        WSThrows = "404:Not Found,500:Internal Server Error")
  RETURNS (DYNAMIC ARRAY ATTRIBUTE(WSName = "accounts") OF
        accountType ATTRIBUTES(XMLName = "account", WSMedia = "application/json, application/xml"))
  
    DEFINE recList DYNAMIC ARRAY OF accountType
 
   # ... function code ...
   
    RETURN recList
END FUNCTION

This function has WSQuery parameters which are optional. This allows the function to be used to query any of the parameter values if provided in the query string of the URL, for example:

http://myhost:6394/gas/ws/r/myGroup/myXcf/MyService/accounts?fname=john&lname=Smith

or

http://myhost:6394/gas/ws/r/myGroup/myXcf/MyService/accounts?lname=Smith

Example WSQuery set as optional on a parameter defined as record

TYPE accountType RECORD
       id VARCHAR(10),
       fname VARCHAR(25),
       lname VARCHAR(25),
       role VARCHAR(25)
       # ...
    END RECORD
    
PUBLIC FUNCTION getAccountRecords(id accountType ATTRIBUTES(WSQuery, WSOptional)
  ATTRIBUTES (WSGet, 
              WSPath = "/accounts",
              WSDescription = "Fetches account records for query value(s) optionally supplied.",
        WSScope = "officestore.user",
        WSThrows = "404:Not Found,500:Internal Server Error")
  RETURNS (DYNAMIC ARRAY ATTRIBUTE(WSName = "accounts") OF accountType )
  
    DEFINE recList DYNAMIC ARRAY OF accountType
 
    # ... function code ...
   
    RETURN recList
END FUNCTION
In the example function the query parameter id is a record. The parameter is optional. This means that all the record fields are optional. The function can respond to client requests:
  • if no query is provided
  • if values for any field are provided
In the example request, two field/value pairs are queried:

http://myhost:6394/gas/ws/r/myGroup/myXcf/MyService/accounts?role=admin&lname=Smith

The GWS deserializes the user fields and values sent by the client in the URL for insertion into the Genero BDL parameter.