WSOptional

Qualifies a parameter as optional in a REST function.

Syntax

WSOptional

WSOptional is an optional attribute.

Usage

You can set WSOptional on the ATTRIBUTES()clause of a parameter when a function does not require the parameter to be present when a client calls the service. Setting parameters as optional is typically used when defining REST functions in the following situations:

If a query string (WSQuery) is not always required, set the input parameter with WSOptional. For an example, see Example use of parameter attributes.
If a custom header (WSHeader), input or output, is not always required, set the parameter with WSOptional. For an example, see Example use of parameter attributes.
If a cookie (WSCookie) is not always required, set the parameter with WSOptional. See Example WSCookie and WSOptional.
If an input body parameter is not always required, set the parameter with WSOptional. See Example optional input body.
Normally, a client request for a service with WSPost, WSPut, or WSPatch requires an input message body, and failing to specify a message body in a request will raise error-9106 or error-9128. With the body parameter defined as optional, an input body request is not required when a client calls the service. For more information, see Set a request body.
Important:
If you have multipart input bodies and any one input body is optional, then all input parameters must set the WSOptional attribute; otherwise fglcomp will raise error-9138.

Example WSCookie and WSOptional

In this sample REST function a set of users is returned based on a value provided in a cookie sent as a header. The function's ccode input parameter is set with the WSCookie, WSName, and the WSOptional attributes.

If the client application calling the function provides a value for the cookie in the request, the name specified by WSName must be set in the query string of the URI, such as http://myhost:6394/gas/ws/r/myGroup/myXcf/Accounts/usersbycountry?country=FRA

In the SQL query of the database, the COALESCE function is used to produce a query that supports the optional parameter. If the cookie is not provided, all users 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 profileType RECORD
     id INTEGER,
     name VARCHAR(100),
     email VARCHAR(255),
     category VARCHAR(10),
     status INTEGER,
     country VARCHAR(3)
     # ...
   END RECORD

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

PUBLIC FUNCTION getUsersByCountry(
     ccode STRING ATTRIBUTE(WSCookie, WSOptional, WSName = "country", 
                            WSDescription = "Country code" )
                            )
  ATTRIBUTES (WSGet,
              WSPath = "/usersbycountry",
              WSDescription = "Gets users with the optional cookie value applied.",
              WSThrows = "400:Invalid,406:@userError" )
   RETURNS ( DYNAMIC ARRAY ATTRIBUTE(WSName = "Users",
             WSMedia = "application/json") OF profileType)
      
     DEFINE arr DYNAMIC ARRAY OF profileType
     DEFINE i INTEGER = 1
     TRY
       # code to get users
       DECLARE c4 CURSOR FOR SELECT * FROM users
                               WHERE users.country = COALESCE(ccode,users.country)
                               ORDER BY users.name ASC         
       # COALESCE function is used to produce a query that supports the optional parameter
       FOREACH c4 INTO arr[i].*
         LET i = i+1
       END FOREACH
       CALL arr.deleteElement(arr.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 arr
END FUNCTION

Example: Optional input body

In this sample REST function the value returned is dependent on whether data has been received in an input body. The function has an input parameter rec that is set with the WSOptional attribute. Therefore, data may or may not be received in the request body.

A user-defined variable Context set with the WSContext attribute is defined in the module. This is used to detect if the client has sent a body at runtime. If the request does not have an input body, the GWS sets the "NoRequestBody" entry in the Context variable to true.

In the function the Context is checked for the status of the "NoRequestBody" entry, and the value the function returns is based on this.

PRIVATE DEFINE Context DICTIONARY ATTRIBUTES(WSContext) OF STRING

PUBLIC
FUNCTION testRecord(rec RECORD ATTRIBUTES(WSOptional) a INTEGER, b INTEGER END RECORD)
  ATTRIBUTES (WSPut, 
             WSPath = "/record",
             WSDescription = "Check for request body with WSContext variable")
  RETURNS (INTEGER)
  IF Context.contains("NoRequestBody") THEN
    DISPLAY Context["NoRequestBody"]
    RETURN 0
  ELSE
     RETURN rec.a + rec.b
  END IF
END FUNCTION