WSAttachment

Defines file attachments in the REST message.

Syntax

WSAttachment [= "regexp_pattern"]

Where:

WSAttachment is an ATTRIBUTE() clause of an input parameter or return value of the function defining a file attached in the REST message.
regexp_pattern is a regular expression value that the file name must match. It is used to limit file names to a set of valid characters to protect against code injection. Using a regex pattern is optional.

WSAttachment is an optional attribute.

Usage

You use this attribute to attach files. Files may be attached in the message response or request.

For example, in order to receive files as attachments, you can have one or more input parameters with the WSAttachment attribute in the request. The client application needs to provide an absolute path to the file for the parameter values when making a call to the function.

There is an option to use a regex pattern to protect against code injection by restricting file names to a set of valid characters, for example, WSAttachment = "[a-zA-Z0-9_]*\.[a-zA-Z0-9_]*". The GWS validates the file name against the given pattern, and raises error-42 if the regex pattern is incorrect or the validation fails. For more information on using regular expressions, see the XML Schema specification.

The file attachment MIME type can be set by the WSMedia attribute. If WSMedia is not specified, the engine accepts it as the OpenAPI specification for all file types, "*/*" .

Example WSAttachment with WSMedia

This example returns a text file as an attachment, defined by the STRING parameter with the WSAttachment attribute. The WSMedia attribute specifies the MIME type as "text/plain". The absolute path to the file is set on the return.

The REST engine copies the file to the temporary directory defined by the TMP environment variable.

Note: The file is removed from the temporary directory at the end of the REST operation to avoid a build-up of files on your disk.

PUBLIC FUNCTION Get() 
   ATTRIBUTES(WSGet) 
   RETURNS (STRING ATTRIBUTE(WSAttachment, WSMedia="text/plain") )
     # ... function code ...
     RETURN "/usr/tmp/myfile.txt"
END FUNCTION

Attaching an image

If you are attaching an image, it is defined in WSMedia with a wildcard to allow for all image types:

input STRING ATTRIBUTE (WSAttachment, WSMedia="image/*")

The payload format is chosen according to that specified in the Content-Type header received from the client using the Web service. You code in your function to replace the image/* placeholder in the Content-Type header with the actual value. This can be done, for instance, using the WSContext attribute, to set the header.

Attaching a file of any type

If the file can be any type, WSMedia is not specified with WSAttachment.

input STRING ATTRIBUTE (WSAttachment)

Attaching a file and validating the filename against a regular expression pattern

In this example, the attachment is defined by the in parameter with the WSAttachment attribute. The file name of the text file received as an attachment is validated against a regular expression pattern.

PUBLIC FUNCTION simpleFile(
    in STRING ATTRIBUTE(WSAttachment = "[a-zA-Z0-9_]*\.[a-zA-Z0-9_]*"))
    ATTRIBUTE(WSPost, WSPath = "/simple/txt")
    RETURNS()
END FUNCTION

The pattern "[a-zA-Z0-9_]*\.[a-zA-Z0-9_]*" limits file names to the allowed characters. Characters not in the class group [a-zA-Z0-9_] in the file name or in the extension are invalid.

Note: The dot . character must be escaped (\.).

If the regular expression on the WSAttachment attribute is invalid, the server will raise error-42 and respond with the HTTP error:

400 Regex syntax error

If the file name of the received file does not match the defined pattern (regexp), the server will raise error-42 and respond with the HTTP error:

400 File name does not match template