WSContext

WSContext defines an injection variable to retrieve REST operation context values at the service level.

Syntax

WSContext

WSContext is an optional attribute.

Usage

Use WSContext to retrieve REST operation context such as BaseURL, Media, and Scope, or to set a default context for the Content-Type header if the WSMedia attribute value contains a wildcard.

You need to define a DICTIONARY variable in your REST module that specifies WSContext in an ATTRIBUTES()clause. The context variable needs to be a private modular variable, otherwise error-9125 is thrown.

PRIVATE DEFINE Context DICTIONARY ATTRIBUTES(WSContext)OF STRING

The GWS engine sets the dictionary key/values before the function is executed. For examples of use in your REST function, see Table 1.

Table 1. Context dictionary
Key	Description	Example usage
Media	The dictionary variable entry contains: one of the media values set in the `WSMedia` attribute of the input parameter; the variable returns the MIME type chosen when several MIME types are possible. the default MIME type when no `WSMedia` attribute has been defined. A media type (also known as Multipurpose Internet Mail Extensions (MIME) type) is an identifier used by the HTTP protocol to denote message content. The format is based on standards from the Internet Assigned Numbers Authority (IANA).	`DISPLAY context["Media"]` This example displays a MIME type. For instance, if WSMedia is set with a list of MIME types (`"application/json,application/xml"`), you can know the exact media type requested in the current execution of the function: `application/xml`.
BaseURL	Contains the base URL of the service when executed. The URL for an application being delivered by the Genero Application Server (GAS) and the URL for an application not behind a GAS differ.	`DISPLAY context["BaseURL"]` This example displays the service's BaseURL, such as: HTTPS://myhost:6394/gas/ws/r/myXcf/Account if the service has been registered as "Account". This may be useful if your REST function has to query another function, and the exact URL is needed.
RequestURL	Contains the URL of the service request from the client app.	`DISPLAY context["RequestURL"]` The request URL may consist of a host name, a port number, a resource path, and a query string. The GWS rebuilds the URL from the context BaseURL value, WSPath, and the function parameter values. You may need the URL to perform a forward or a redirect to another service.
Scope	Contains the valid scope (if there is one) that grants access to the REST function.	`DISPLAY context["Scope"]` This may display "profile.read". For instance, if `WSScope access (function)` has been set in the function with a list of scopes ("profile.read, profile.write, profile.mgr"), it may be useful to know which one really applies in the current function execution.
RequestPATH	Contains the `WSPath` attribute value of the current REST operation.	`RequestPath=/complexxml/{coeff}` The path will be needed by the REST engine to perform preprocessing or postprocessing callbacks.
RequestVERB	Contains the HTTP Verb of the current REST operation.	`RequestVERB=POST` The request verb will be needed by the REST engine to perform preprocessing or postprocessing callbacks.
RequestOPERATION	Contains the name of the current REST operation.	`RequestOPERATION=TestEchoXML` The name of the request operation will be needed by the REST engine to perform preprocessing or postprocessing callbacks.
Content-Type	Contains the real MIME type the REST function returns if the `WSMedia` attribute value contains "image/*". Tip: You can set the `Content-Type` in a multipart response to transfer data of different MIME types in the same message. See Example WSContext with multipart Content-Type set at runtime.	Important: This is the only context dictionary value you can set at runtime. `LET context["Content-Type"]="image/jpeg"` This statement will set the returned `Content-Type` header to "image/jpeg". For more examples, see Set WSContext with Content-Type at runtime

Set WSContext with Content-Type at runtime

If the WSMedia return parameter attribute has a list of values or a wildcard value, "image/*", you code in a function to set the Content-Type header for the actual value returned at runtime in the response. Table 2 outlines options for defining the Content-Type header for the image.

Table 2. Content-Type Header
Header type	Header Name	Description	Example
Default header	`Content-Type`	Setting the header with the format of the image when returning one file.	`LET Context["Content-Type"]="image/png"`
Custom header	`name`.`Content-Type`	Setting custom headers via GWS default naming.	`LET Context["rv0.Content-Type"]="image/png"`
Custom header	`name`.`Content-Type`	Setting custom headers with parameters set with WSName.	`LET Context["hello.Content-Type"]="image/jpg"`

Example WSContext with Content-Type set at runtime

In this sample REST function an image file is requested and returned by the service if available. The WSParam attribute is set on the function's id parameter as the path template for the image to return. The client passes a value for the id parameter in the URL (124143 in the example):

http://myhost:6394/gas/ws/r/myGroup/myXcf/MyService/photos/124143

The WSName attribute value set in the return parameter to define the header, "image.Content-Type" in the Context variable. The header value is set to the actual image type, depending on whether it is a jpg or a png type image is returned.

If the image is not found, the message field of the userError variable is set, and a call to SetRestError() returns the message to the client.

IMPORT com
IMPORT os

PRIVATE DEFINE Context DICTIONARY ATTRIBUTES(WSContext) OF STRING

PUBLIC FUNCTION getImage( id INTEGER ATTRIBUTES(WSParam) )
  ATTRIBUTES(WSGET,
             WSPath = "/photos/{id}" )
  RETURNS STRING ATTRIBUTES (WSAttachment, WSName = "image", WSMedia = "image/*")
    DEFINE img STRING
    DEFINE ok BOOLEAN
    
    LET ok = FALSE
    IF os.Path.exists("usr/app/files/"|| id || ".png") THEN
       LET img = "usr/app/files/"|| id || ".png"
       LET Context["image.Content-Type"] = "image/png"
       LET ok = TRUE
    ELSE
      IF os.Path.exists("usr/app/files/"|| id || ".jpg") THEN 
        LET img = "usr/app/files/"|| id || ".jpg"
        LET Context["image.Content-Type"] = "image/jpg"
        LET ok = TRUE
      END IF
    END IF
    IF NOT ok THEN
      LET userError.message = "File does not exist"
      CALL com.WebServiceEngine.SetRestError(404,userError)
    END IF
    RETURN img
END FUNCTION

Example WSContext with multipart Content-Type set at runtime

In this sample REST function a multipart response body is defined to return three images of different media types. A Content-Type header for each image is set using the Context dictionary and the value is set to the actual image type returned.

In the example, the Content-Type header for the first parameter is set with the GWS REST engine's default naming for headers that start with "rv0": rv0.Content-Type. The second parameter, using the WSName attribute, is given the name "hello.Content-Type". The third parameter continues with the default sequence and is set to rv2.Content-Type.

PRIVATE DEFINE Context DICTIONARY ATTRIBUTES(WSContext) OF STRING

PUBLIC FUNCTION getMultiImage() 
  ATTIBUTES(WSGet,
            WSPath = "/photos") 
  RETURNS (BYTE, BYTE ATTRIBUTES(WSName = "hello"), BYTE)
  DEFINE b0,b1,b2 BYTE

  # ... function code ...
  
  LET Context["rv0.Content-Type"] = "image/png"
  LET Context["hello.Content-Type"] = "image/jpg"
  LET Context["rv2.Content-Type"] = "image/gif"
  # ...
  RETURN b0,b1,b2
END FUNCTION