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 ATTRIBUTES() 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?firstname=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.

The GWS and fglrestful supports serialization and deserialization of parameters according to defaults set by the OpenAPI specification. 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

In this sample REST function WSQuery and WSOptional is set on three input parameters. 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?firstname=john&lastname=Smith

or

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

In the SQL query of the database, the COALESCE function is used to produce a query that supports the optional parameters. If no parameter is provided, all accounts are returned.

WSThrows is set to handle errors. In the TRY/CATCH block, the sqlca record is checked after the execution of the SQL query. The SQLERRMESSAGE is set to the message field of the userError variable, and a call to SetRestError() returns the message defined in WSThrows for the error. 

IMPORT com

TYPE accountType RECORD
         userid VARCHAR(80),
         firstname VARCHAR(80),
         lastname VARCHAR(80),
         email VARCHAR(80)
   END RECORD
    
PUBLIC FUNCTION getAccountRecords(
    resourceId STRING ATTRIBUTES(WSQuery, WSOptional, WSName = "id"),
    fname STRING ATTRIBUTES(WSQuery, WSOptional, WSName = "firstname"),
    lname STRING ATTRIBUTES(WSQuery, WSOptional, WSName = "lastname"))
  ATTRIBUTES (WSGet,
              WSPath = "/accounts",
              WSDescription = "Fetches the accounts resource with the optional filter value(s) applied.",
        WSScope = "officestore.user",
        WSThrows = "404:Not Found,406:@userError,500:Internal Server Error")
  RETURNS (DYNAMIC ARRAY ATTRIBUTES(WSName = "accounts") OF
        accountType ATTRIBUTES(XMLName = "account", WSMedia = "application/json, application/xml"))
  
    DEFINE recList DYNAMIC ARRAY OF accountType
    DEFINE i INTEGER = 1
     TRY
       DECLARE c5 CURSOR FOR SELECT * FROM account
                               WHERE account.userid = COALESCE(resourceId,account.userid)
                               AND account.firstname = COALESCE(fname,account.firstname)
                               AND account.lastname = COALESCE(lname,account.lastname)
                               ORDER BY account.userid ASC           
       # COALESCE function is used to produce a query that supports the optional parameters
       FOREACH c5 INTO recList[i].*
         LET i = i+1
       END FOREACH
       CALL recList.deleteElement(recList.getLength())
       # Remove the empty element implied by reference in FOREACH loop 
     CATCH
       LET userError.message = SFMT("Error in SQL execution: %1 [%2]", sqlca.sqlcode, SQLERRMESSAGE )
       CALL com.WebServiceEngine.SetRestError(406,userError)
     END TRY
    RETURN recList
END FUNCTION

Example WSQuery set as optional on a parameter defined as record

In this sample REST function the query parameter accRec is a record type with two fields. 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 provided in the query string of the URL:

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

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

In the SQL query of the database, the COALESCE function is used to produce a query that supports the optional parameters. If no parameter is provided, all accounts are returned.

WSThrows is set to handle errors. In the TRY/CATCH block, the sqlca record is checked after the execution of the SQL query. The SQLERRMESSAGE is set to the message field of the userError variable, and a call to SetRestError() returns the message defined in WSThrows for the error. 

IMPORT com

TYPE accountType RECORD
         userid VARCHAR(80),
         firstname VARCHAR(80),
         lastname VARCHAR(80),
         email VARCHAR(80),
         category VARCHAR(10)
  END RECORD
    
PUBLIC FUNCTION getAccountRecord(accRec
  RECORD ATTRIBUTES(WSQuery, WSOptional) category STRING, lastname STRING END RECORD  )
  ATTRIBUTES (WSGet, 
              WSPath = "/accounts/rec",
              WSDescription = "Fetches account records for query value(s) optionally supplied.",
        WSScope = "officestore.user",
        WSThrows = "404:Not Found,406:@userError,500:Internal Server Error")
  RETURNS (DYNAMIC ARRAY ATTRIBUTES(WSName = "Users") OF accountType )
  
    DEFINE recList DYNAMIC ARRAY OF accountType
    DEFINE i INTEGER = 1
      TRY
        DECLARE c8 CURSOR FOR SELECT * FROM users
                               WHERE users.category = COALESCE(accRec.category,users.category)
                               AND users.lname = COALESCE(accRec.lastname,users.lname)
                               ORDER BY users.id ASC                     
        # COALESCE function is used to produce a query that supports the optional parameters
        FOREACH c8 INTO recList[i].*
          LET i = i+1
        END FOREACH
        CALL recList.deleteElement(recList.getLength())
        # Remove the empty element implied by reference in FOREACH loop    
      CATCH
        LET userError.message = SFMT("Error in SQL execution: %1 [%2]", sqlca.sqlcode, SQLERRMESSAGE )
        CALL com.WebServiceEngine.SetRestError(406,userError)
      END TRY
    RETURN recList
END FUNCTION