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.

WSHeader is an optional attribute.

Usage

You use the WSHeader attribute to define a custom header in input parameters and in return values. Custom headers are commonly used for informational purposes, but you can also use them for passing data to implement logic on the server or client side.

A typical use of WSHeader is to pass data related to the service in the form of HTTP header. For example, setting ATTRIBUTE(WSHeader, WSName="Authorization") on an input parameter can be used to set the standard HTTP authorization header, if there is one.

Use WSName with WSHeader to name headers, otherwise the GWS gives the headers default names, "rv0", "rv1", etc., at runtime.

Example WSHeader in input parameter

In the sample function, a header named "X-FourJs-Environment-Variable-REMOTE_ADDR" passes the Genero Application Server environment variable for the IP address of the remote client.

This variable has hyphens ("-"), which are not allowed in Genero BDL variables. The parameter name (ip_addr) is BDL friendly and is used in the function. In the HTTP request, there will be a header named "X-FourJs-Environment-Variable-REMOTE_ADDR", set by WSName. The parameter 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.

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

Example WSHeader in return value

In this example, a custom header is defined in the RETURNS clause of the function. The integer ("3") is returned in the header and the string ("hello world" ) is returned in the response body.

Warning: Standard response headers

Setting a standard HTTP header on a response must be handled with care, especially for those that define the response body such as Content-Type, or Content-Encoding. Make sure what you define with WSName does not conflict with what is specified in the OpenAPI specification for the service.

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