com.WebServiceEngine.SetRestError

Manages error handling for a REST high-level Web Service function.

Syntax

com.WebServiceEngine.SetRestError(
   code INTEGER
   error RECORD )

code defines a standard HTTP response status code (400 - 599) as defined in RFC 2616 Section 10.4 and RFC 2616 Section 10.5
error defines details of the error. It can be NULL, a string value, or reference a modular variable.

Usage

You use this method to set the REST error code and details of the error to be returned to the client when the request to the resource has finished. There are two ways to use the method.

You can call the method with a code and error specified with the attribute WSThrows. In this example the standard HTTP status code (400 Bad Request) is defined with details of the error in the "myError" variable. In your function, you code to trap the error at runtime with a call to the SetRestError() method.

This method must be called inside a Web Service REST high-level function.

Example 1: managing errors with WSThrows and WSError

PUBLIC DEFINE myError RECORD ATTRIBUTE(WSError="user error")
  message STRING
END RECORD

PUBLIC
FUNCTION queryAccountById(id VARCHAR(10) ATTRIBUTE(WSParam)
    )
    ATTRIBUTES(WSGet,
        WSPath="/accounts/{id}",
        WSThrows="400:@myError,500:Internal Server Error")
    RETURNS accountType ATTRIBUTES(WSName="body")

  DEFINE thisAccount RECORD LIKE accounts.*
  # ... retrieve user id from database ...

    CASE sqlca.sqlcode
    WHEN 0
        EXIT CASE
    WHEN NOTFOUND
        LET myError.message = SFMT("Could not find account id :%1",id)
        CALL com.WebServiceEngine.SetRestError(400,myError)
    OTHERWISE
          CALL com.WebServiceEngine.SetRestError(500,NULL)
    END CASE
    RETURN thisAccount.*
END FUNCTION

The SetRestError() method must get the exact variable defined in the WSThrows declaration, otherwise the method fails and returns an error code of -15570

The second use option provides a method you can use to code for unexpected errors.

Warning: In general, the recommended option is to list all the possible errors as shown in Example 1, in order to get them generated in the OpenAPI specification file and trapped on the client side.

With this option you code to trap a code number not defined in the WSThrows list with a call to the SetRestError() method. SetRestError() then returns the error code and optionally the error variable.

Example 2: managing unexpected errors

PUBLIC DEFINE myError RECORD ATTRIBUTE(WSError="user error")
  message STRING
END RECORD

PUBLIC
FUNCTION queryAccountById(id VARCHAR(10) ATTRIBUTE(WSParam)
    )
    ATTRIBUTES(WSGet,
        WSPath="/accounts/{id}",
        WSThrows="400:@myError,500:Internal Server Error")
    RETURNS accountType ATTRIBUTES(WSName="body")
  
  DEFINE thisAccount RECORD LIKE accounts.*
  # ... retrieve user id from database ...

    CASE sqlca.sqlcode
    WHEN 0 # success
        EXIT CASE
    WHEN NOTFOUND
        LET myError.message = SFMT("Could not find account id :%1",id)
        CALL com.WebServiceEngine.SetRestError(400,myError)
    WHEN < 0 
        CALL com.WebServiceEngine.SetRestError(500,NULL)
    OTHERWISE
       CALL com.WebServiceEngine.SetRestError(505,NULL)
    END CASE
    RETURN thisAccount.*
END FUNCTION