WSHeader

Defines custom headers in the request and response of Web service functions.

Syntax

WSHeader

Where:

WSHeader is defined in an ATTRIBUTE() clause in an input parameter or return value of the function.

Usage

You use the WSHeader attribute to define a custom header. It is valid to set this in input parameters and in return values. A typical use of WSHeader is to pass data related to the service in the form of HTTP header.

Example WSHeader in input parameter

IMPORT com

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

PUBLIC FUNCTION getRemoteAddress (ip_addr STRING 
   ATTRIBUTE(WSHeader, WSOptional, WSName="X-FourJs-Environment-Variable-REMOTE_ADDR") )
   ATTRIBUTES (WSGet, 
              WSPath="/users/ip",
              WSDescription="Get remote address of the client",
              WSThrows="400:Invalid,404:NotAvailable" )
   RETURNS ( INTEGER ATTRIBUTE(WSHeader), STRING)
     DEFINE ip STRING
     TRY
       LET ip=ip_addr
       IF ip IS NULL THEN 
          LET ip="Got no remote address."
       ELSE
         LET ip = SFMT("Hello there, you're at %1",ip )
       END if
     CATCH
       LET ip="Error getting remote address."
       LET myerror.reason = SFMT("Error during execution: %1 [%2]", SQLCA.SQLCODE, SQLERRMESSAGE )
       CALL com.WebServiceEngine.SetRestError(400,myerror)
     END TRY
     RETURN 3, ip
END FUNCTION

In the call to the function, a header named "X-FourJs-Environment-Variable-REMOTE_ADDR" provides the IP address of the remote client. The input is optional as defined by the attribute WSOptional.

Tip: The WSContext attribute, if set, can provide your service with access to environment variables set by the GAS.

Example WSHeader in return value

PUBLIC FUNCTION help() 
  ATTRIBUTES (WSGet)
  RETURNS (INTEGER ATTRIBUTE(WSHeader), 
    STRING)
    # ... function code  ...
    RETURN 3, "hello world"
END FUNCTION

In the response, you define a custom header in the RETURNS clause of your function.

In the HTTP output the integer ("3") is returned in the header and the string ("hello world" ) is returned in the response body.

Unnamed parameters and return values are given default names, "rv0", "rv1", etc., at runtime. You can change default header naming via the WSName attribute, for example with: ATTRIBUTE(WSHeader, WSName="MyHeader")