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. It is returned in the response message body.
- There is no space before or after the colon (
:
). - If you use the code option on its own without a description, the default fault description defined in RFC 2616 is returned to the client.
WSThrows
is an optional attribute.
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.
WSThrows
:error-9117
.WSThrows = "404, 402"
- In this example, there are no descriptions of the error, just 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
.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. Otherwise the web server may replace your description with the standard HTTP error message.
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. These will be returned in the message body.
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