WSOptional

Qualifies a parameter as optional in a REST function.

Syntax

WSOptional

WSOptional is an optional attribute.

Usage

You can set WSOptional on the ATTRIBUTE()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: Optional cookie.
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 as optional.
Note: 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: Optional cookie

IMPORT  com

TYPE profileType RECORD
     id INT,
     name VARCHAR(50),
     email VARCHAR(100),
     ccode VARCHAR(10)
     # ...
   END RECORD

DEFINE myError RECORD ATTRIBUTE(WSError="My error")
  code    INTEGER,
  reason  STRING
END RECORD

PUBLIC FUNCTION getUsersByCountry(
     p_country STRING ATTRIBUTE(WSCookie, WSOptional, WSName = "Preferred_country" ) )
  ATTRIBUTES (WSGet, 
              WSPath="/users",
              WSDescription="Get users by country if the cookie is sent by client.",
              WSThrows="400:Invalid,404:NotAvailable" )
  RETURNS (
    DYNAMIC ARRAY ATTRIBUTE(WSName="Users",WSMedia="application/xml,application/json") OF profileType 
    )
  
    DEFINE countryList DYNAMIC ARRAY OF profileType
    IF p_country IS NULL THEN
        SELECT * FROM users 
    ELSE 
        SELECT * FROM users WHERE @ccode=p_country
    END IF
     # ... function code  ...
    RETURN countryList
END FUNCTION

Example: Optional input body

This example sets WSOptional attribute on the parameter (rec) for the input message body.

You must code in the function to have WSContext detect whether the client has sent a body at runtime. If the request does not have an input body parameter, the GWS sets the "NoRequestBody" entry in the WSContext variable to true.

PRIVATE DEFINE Context DICTIONARY ATTRIBUTE(WSContext) OF STRING

PUBLIC
FUNCTION TestRecord(rec RECORD ATTRIBUTE(WSOptional) a INTEGER, b INTEGER END RECORD)
  ATTRIBUTE (WSPut, WSPath="/record")
  RETURNS (INTEGER)
  IF Context.contains("NoRequestBody") THEN
    DISPLAY Context["NoRequestBody"]
    RETURN 0
  ELSE
    RETURN rec.a + rec.b
  END IF
END FUNCTION