WSThrows

Defines a list of errors that may be encountered accessing a REST resource.

Syntax

WSThrows = "{ code | code:description | code:@variable } [,...]"

WSThrows is a comma-separated list of status codes and/or error descriptions where:

code is an HTTP status code in the range 400 to 599
description is text describing the error
@variable is a reference to a variable defined to handle error descriptions. The variable must be defined with a WSError attribute.

Important: There is no space before or after the colon (:). If you use the code option without a description, the default fault description defined in RFC 2616 is returned to the client.

Usage

You use this attribute to manage application level errors, such as a database record not found. If your function can potentially return one or more errors, you use WSThrows to declare those so that they can be generated in the OpenAPI specification for that resource.

For instance, HTTP status code 404 means resource not found, but using the WSThrows attribute you can respond to the client with 404:user id not found in your function. To return a description of the status code like this, you must use WSThrows with the "code:@variable" option of the attribute, and reference a variable with the WSError attribute.

If you simply need to return an error code without a description, use WSThrows with code, or with a description use code:description.

For example, these are valid uses of WSThrows:

Important: You must use valid HTTP status codes. Use of HTTP status codes between 400 to 599 are valid, but use of codes between 200 to 399 representing successful HTTP status, results in error-9117.

WSThrows = "404, 402": In this example, there are no descriptions of the error, just standard HTTP response status codes. Standard HTTP error messages ( see RFC 2616 ) are returned and displayed on the client side.
WSThrows= "404:not found error, 402:hello world": In this example, the content after the colon (:) is the description of the error displayed on the client side.
WSThrows= "404:@error1, 402:@error2": Here error descriptions are provided in the WSError attributed variables referenced in @error1 and @error2.
It may happen that the web server replaces your description with the standard HTTP error message. It is recommended that if you need to ensure an error description other than the standard protocol message is returned to the client, you must use WSThrows with the "code:@variable" option.

WSThrows is an optional attribute.

Example function using WSThrows

In the example, the WSThrows attribute is set on the ATTRIBUTES() clause of the function. It has options to respond to a list of errors.

At runtime when errors are trapped, descriptions of the errors are generated. These are set in the myError and fatalError variables, which are defined with the WSError attribute.

A call is made to the SetRestError() method to return the HTTP status code, referencing the appropriate WSThrows option.

IMPORT com  

TYPE profileType RECORD
     id INT,
     name VARCHAR(50),
     email VARCHAR(100)
   END RECORD

PUBLIC DEFINE fatalError INTEGER ATTRIBUTE(WSError="fatal error")
 
PUBLIC DEFINE myError RECORD ATTRIBUTE(WSError="My error")
  code INTEGER,
  reason STRING
END RECORD

PUBLIC FUNCTION updateUser( thisUser profileType )
  ATTRIBUTES (WSPost, 
              WSPath ="/users",
              WSDescription ="Update user details",
              WSThrows ="400:@myError,
                412:@fatalError,406:should not happen" )
  RETURNS STRING
    DEFINE ret STRING
    TRY
      UPDATE users SET 
         name = thisUser.name, 
         email = thisUser.email 
         WHERE @id = thisUser.id
         IF SQLCA.SQLCODE = 0 THEN 
           LET ret = thisUser.id
         END if
    CATCH
      CASE 
          WHEN SQLCA.SQLCODE = NOTFOUND
            LET myError.code = NOTFOUND
            LET myError.reason = SFMT("User with ID: %1 not found",thisUser.id)
            CALL com.WebServiceEngine.SetRestError(400,myError)
          WHEN SQLCA.SQLCODE < 0 
            LET fatalError = SQLCA.SQLCODE
            CALL com.WebServiceEngine.SetRestError(412,fatalError)
          OTHERWISE 
            CALL com.WebServiceEngine.SetRestError(406,NULL)
        END CASE
    END TRY
    RETURN ret
END FUNCTION