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.

Example definition for WSContext dictionary

Important:

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. Note: 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.
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 and/or with parameters set with `WSName` when returning more than one file in a multpart message.	`LET Context["rv0.Content-Type"]="image/png" LET Context["hello.Content-Type"]="image/jpg"`

Example WSContext with Content-Type set at runtime

PRIVATE DEFINE Context DICTIONARY ATTRIBUTES(WSContext) OF STRING

PUBLIC FUNCTION getImage( id INTEGER ATTRIBUTES(WSParam) )
  ATTRIBUTES(WSGET,
             WSPath="/photos/{id}" )
  RETURNS STRING ATTRIBUTES (WSAttachment, WSMedia="image*/") 
    DEFINE image BYTE
    DEFINE mime STRING
    # function code
    CASE mime
    WHEN "png"  
      LET Context["Content-Type"]="image/png"
    WHEN "jpg"
      LET Context["Content-Type"]="image/jpg"
    END CASE
    RETURN image
END FUNCTION

Example WSContext with multipart Content-Type set at runtime

In this example the function defines a multipart response body, returning three images of different types. A Content-Type header for each part is set using the Context dictionary and the value is set to the actual image type returned.

Separate parts are identified by the GWS REST engine's naming convention sequence for headers and body parts that start with "rv0" and goes to the "rvn^th" number of parts. You can change default header naming by adding a value in the WSName attribute to your parameter.

You code for parameters using default header names, by prefacing the header with the default name. For example, the first parameter is rv0.Content-Type, the second rv1.Content-Type, and so on. You code for the parameter using the WSName attribute, by prefacing the header with its name: "hello.Content-Type" in the sample.

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