Handling application level errors

Errors can be handled in your REST function so as to provide an error message to the client that is more helpful and descriptive than the default HTTP error response.

Errors in calls to Web services may occur for various reasons; such as unexpected user input, an unavailable resource, erroneous server response, database connection, etc. More often than not when a call to a function fails, it is for a reason that you can usually anticipate.

For example, if the client tries to access a user record in a database or download a file and that REST operation fails because the user or file does not exist, wouldn't you prefer to respond to the client about creating the file or user record instead of terminating the process with a generic HTTP response?

In any case, it is recommended to take into account the possibility of an error and take appropriate action in your code to ensure that errors are handled and that an appropriate response is returned to the client.

Define error attributes

In GWS REST you can perform error handling using the attributes WSError and WSThrows. The purpose of these attributes is to encode error-handling information. They provide your service with an error handling mechanism (as in SOAP) to give context to the exceptions. When errors are encountered, for example, you can provide the standard HTTP error code with an error description that is more appropriate and specific.

For instance, HTTP status code 400 means bad request, but using the attributes you can respond to the client with, for example, 400:user id not found in your function.

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

You can opt to use these attributes:

WSError

You can define this attribute at the modular level in any 4GL public variable. It allows you to specify an error description that can be reused by different REST functions. It is suited to modeling typical error conditions. For example,

PUBLIC DEFINE AccountError RECORD ATTRIBUTE(WSError="Account error")
  code INTEGER,
  detail STRING
END RECORD

It allows for the addition of information about the nature of an error to be updated at runtime, such as, "Database connection failed".

WSThrows

You can use this attribute in the attributes clause of your function. You use it to declare a list of error codes with or without descriptions that may be thrown when something unexpected happens in the normal flow of execution. For example, these are valid uses of WSThrows:

WSThrows = '404, 402' In this example, there are no descriptions of the error, just standard HTTP response 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.

Handling Errors

In your function, you code to trap the error at runtime with a call to SetRestError() method, for example, com.WebServiceEngine.SetRestError(code, modularVar).

This checks for a valid error according to what you have declared in WSThrows. The SetRestError() method must get the exact variable defined in the WSThrows declaration, otherwise the method fails and returns an error code of -15570.

Publishing errors

When you generate the service description, the errors you declared in the WSThrows attribute, the code reference and the error detail, is published in the "responses" section for that function in the OpenAPI specification file. The modular variables declared with WSError attribute are found in the "component" section at the end of the specification file.