WSContext
Defines an injection variable to retrieve REST operation context values at the service level.
Syntax
WSContext
WSContext
is an optional attribute.
Usage
You can use it to retrieve REST operation context such as BaseURL, Media, and Scope, or you can
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 ATTRIBUTE()
clause.
Example definition for WSContext dictionary
PRIVATE DEFINE Context DICTIONARY ATTRIBUTE(WSContext)OF STRING
Key | Description | Example usage |
---|---|---|
Media | Provides one of the media values set in the WSMedia attribute of the input
parameter. Or it provides the defaults if there is no attribute, or what the REST engine has chosen
when several are possible. |
This may display, for instance,
application/xml . If, for instance, 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. |
BaseURL | Provides the base URL of the service when executed. For example, the URL is not the same in standalone as behind a GAS. | This 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, for instance, and when the exact URL is needed. |
Scope | Provides the valid scope (if there is one) that grants access to the REST function. | This may display "profile.read".If, for
instance, |
Content-Type | Provides 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. For example, this
statement will set the returned Content-Type header to "image/jpeg" based on the
media type requested at runtime. |
Set WSContext with Content-Type at runtime
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. Header Name | Description | Example |
---|---|---|
Content-Type |
Setting the header with the format of the image when returning one file. |
|
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. |
|
Example WSContext with Content-Type set at runtime
PRIVATE DEFINE Context DICTIONARY ATTRIBUTE(WSContext) OF STRING
PUBLIC FUNCTION getImage( id INTEGER ATTRIBUTE(WSParam) )
ATTRIBUTES(WSGET,
WSPath="/photos/{id}" )
RETURNS STRING ATTRIBUTE (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
"rvnth" number of parts. You can change default header naming by adding a value in the
WSName
attribute to your
parameter.
The parameters using default header names, you code 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. The parameter using the WSName
attribute, you set by prefacing
the header with its name, "hello.Content-Type
" in the sample.
PRIVATE DEFINE Context DICTIONARY ATTRIBUTE(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