WSAttachment

Defines file attachments in the REST message.

Syntax

WSAttachment [= "regexp_pattern"]
Where:
  1. WSAttachment is an ATTRIBUTES() clause of an input parameter or return value of the function defining a file attached in the REST message.
  2. regexp_pattern is a regular expression value that the filename must match. It is used to limit filenames 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 filenames to a set of valid characters, for example, WSAttachment = "[a-zA-Z0-9_]*\.[a-zA-Z0-9_]*". The GWS validates the filename 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

In this sample REST function a text file is returned as an attachment. In the return clause of the function a STRING is defined 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 string.

The REST engine copies the file to the temporary directory defined by the TMP environment variable. 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.

IMPORT com
IMPORT os

PUBLIC DEFINE userError RECORD ATTRIBUTE(WSError = "User error")
  message STRING
END RECORD

PUBLIC FUNCTION GetReadme() 
   ATTRIBUTES(WSGet,
              WSPath = "/file/README",
              WSDescription = "Returns a text file",
              WSThrows = "404:@userError") 
   RETURNS (STRING ATTRIBUTES(WSAttachment, WSMedia = "text/plain") )
     DEFINE ret, fname STRING
     DEFINE ok INTEGER

     LET fname = "/myservice/files/README"
     LET ok = os.Path.exists(fname)
     IF ok THEN
       LET ret = fname
     ELSE
       LET userError.message = SFMT("File (%1) does not exist", fname)
       CALL com.WebServiceEngine.SetRestError(404,userError)
     END IF
     RETURN ret
END FUNCTION

Attaching files in request and response

In this sample REST function, an image file is sent to the server in the request and another image is returned to the client. The wildcard (image/*) in WSMedia allows for all image types. If the file can be any type, WSMedia is not specified with WSAttachment.

The format is chosen according to that specified in the Accept or Content-Type headers. You code in your function to replace the image/* placeholder in the Accept or Content-Type header with the actual value. This can also be done using the WSContext attribute to set the header.

IMPORT os

PUBLIC FUNCTION EchoFile( input STRING ATTRIBUTES (WSAttachment,WSMedia = "image/*") )
  ATTRIBUTES(WSPost)
  RETURNS STRING ATTRIBUTES (WSAttachment, WSMedia = "image/*")
    DEFINE ok INTEGER
    LET ok = os.path.rename(input, "MyFile.png")
    RETURN "/usr/local/MyOtherFile.jpg"
END FUNCTION

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

In this sample REST function, an attachment is specified by the in parameter with the WSAttachment="[a-zA-Z0-9_]*\.[a-zA-Z0-9_]*" attribute. The filename received is validated against the regular expression pattern, which limits filenames to the allowed characters. Characters not in the class group [a-zA-Z0-9_] in the filename or in the extension are invalid.

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 filename 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
PUBLIC FUNCTION simpleFile(
    in STRING ATTRIBUTES(WSAttachment = "[a-zA-Z0-9_]*\.[a-zA-Z0-9_]*"))
    ATTRIBUTES(WSPost, WSPath = "/simple/txt")
    RETURNS()
END FUNCTION