WSThrows

Declares a list of REST errors.

Syntax

WSThrows = "{ code | code:description | code:@variable } [,...]"
Where WSThrows is a comma-separated list of errors and where:
  1. code is an HTTP status code in the range 400 to 599
  2. description is a string describing the error
  3. @variable is a reference to a variable defined as public at the modular level, and where the error description is 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 errors if your function can potentially return one or more errors. You set the WSThrows attribute in the ATTRIBUTES() clause of the function. You code for the error by setting a call to the SetRestError method at runtime.

For instance, HTTP status code 404 means not found, but using the WSThrows attribute you can respond to the client with 404:user id not found in your function.

WSThrows is an optional attribute.

Example WSThrows

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 = SFMT("Updated user with ID: %1",thisUser.id)
         END if
    CATCH
      LET ret=SFMT("Error updating user with ID: %1",thisUser.id)
      CASE 
          WHEN SQLCA.SQLCODE = NOTFOUND
            LET myError.reason = SFMT("User with ID: %1 not found",thisUser.id)
            CALL com.WebServiceEngine.SetRestError(400,myError)
          WHEN SQLCA.SQLCODE < 0 
            LET myError.reason = "Internal error"
            CALL com.WebServiceEngine.SetRestError(412,fatalError)
          OTHERWISE 
            LET myError.reason = SFMT("SQL error in update execution: %1 [%2]", SQLCA.SQLCODE, SQLERRMESSAGE )
            CALL com.WebServiceEngine.SetRestError(406,myError)
        END CASE
    END TRY
    RETURN ret
END FUNCTION