Processing REST requests

PolicyCenter calls the methods on the plugin IRestDispatchPlugin interface during the processing of all REST requests. Use the interface methods to control output and logging. As the methods callbacks occur during the processing of a request, Guidewire recommends that these methods not throw exceptions as it is possible for a an exception to hide an operational or serialization error.

Public interface IRestDispatchPlugin contains the following public methods.

handleReceiveRequest(requestContext)

PolicyCenter calls the handleReceiveRequest method upon receipt of each REST request. At this point in the processing of the request, the REST API framework:

• Has not yet determined the proper operation to take. (The API request can request an unsupported path.)
• Has not authenticated the client that called the request.
• Has not checked permissions for the request.

This method takes the following argument only.

Method argument	Null?	Description
requestContext	No	A RequestContext object that contains information about this request. See class RequestContext for useful properties on this object.

If this method throws an exception, it passes the associated ErrorInfo JSON object as the argument to the plugin handleRequestProcessed method:

• If the exception thrown by the plugin method implements the HasErrorInfo interface, the method passes an ErrorInfo object to the operationError argument of the handleRequestProcessed method.
• If the exception does not implement the HasErrorInfo interface, the method passes a generic ErrorInfo object with a response code of 500.

Note: It is possible to implement your own version of this method so that it extracts tracking information, if you also implement the necessary traceability IDs. In your version of this method, you can also implement logging of the incoming request, as well. If you do implement your own version of this method, you need to take into account that, at this stage, the REST request can potentially be an attack and not a legitimate request.

handlePreExecute(requestContext, user)

PolicyCenter calls the handlePreExecute method just prior to setting up the execution environment for the requested operation. If the request requires authentication to perform, this method performs authentication of the user requesting the operation. The handlePreExecute method also determines the correct handler to use to process the request.

This method takes the following arguments.

Method argument	Null?	Description
requestContext	No	A RequestContext object that contains information about this request. See class RequestContext for useful properties on this object.
user	Yes	A User object that represents the user requesting the operation. It is possible for this value to be null if the request does not require user authentication.

If this method throws an exception, it passes the associated ErrorInfo JSON object as the argument to the plugin handleRequestProcessed method:

• If the exception thrown by the plugin method implements the HasErrorInfo interface, the method passes an ErrorInfo object to the operationError argument of the handleRequestProcessed method.
• If the exception does not implement the HasErrorInfo interface, the method passes a generic ErrorInfo object with a response code of 500.

rewriteResponse(requestContext, response)

If PolicyCenter calls the operation handler on this request and the handler returned successfully, PolicyCenter calls this plugin method just prior to serializing (writing) the response to the request.

This method takes the following arguments.

Method argument	Null?	Description
requestContext	No	A RequestContext object that contains information about this request. See class RequestContext for useful properties on this object.
response	No	The Response object that represents the response to the request. Generally, the method creates the Response object from the operation handler return value.

The rewriteResponse method returns a Response object, which can simply be the Response object passed to the method initially. If the request handler was successful in processing the request, the handler returns a Response object with a 4xx or 5xx code status.

If serialization fails for some reason:

• The rewriteResponse method generates an error of type serializationError.
• The handlerResponse and serializedResponse objects represent different things:
  • The handlerResponse object contains whatever the request handler returned.
  • The serializedResponse object contains a 5xxx error code that represents the reason for the server-side failure.

rewriteErrorInfo(requestContext, errorInfo)

PolicyCenter calls the rewriteErrorInfo method if processing the client request generates an error. This error can occur during any of the following phases of the request:

• During set up of the request
• During execution of the requested operation
• During serialization (writing) of the response returned from a successful completion of executed operation

This method takes the following arguments.

Method argument	Null?	Description
requestContext	No	A RequestContext object that contains information about this request. See class RequestContext for useful properties on this object.
errorInfo	No	An ErrorInfo object that represents the error that occurred. Do not attempt to change the value of the passed-in errorInfo object in this method, as the rewriteErrorInfo method passes the passed-in object to method handleRequestProcessed.

The rewriteErrorInfo method returns an ErrorInfo object that is one of the following:

• The passed-in ErrorInfo object
• A custom ErrorInfo object that you create

If you want to create your own version of this method that returns a custom ErrorInfo object, add the passed-in value of the errorInfo argument as a detail of your newly created ErrorInfo object.

PolicyCenter serializes the ErrorInfo object and sends it as the response to the REST request.

handleRequestProcessed(requestContext, elapsedMs, handlerResponse, operationError, serializedResponse, serializationError, writeException)

PolicyCenter explicitly invokes the handleRequestProcessed method after it finishes processing the request and after it closes the response output stream. This is to ensure the time spent in this method does not contribute to the latency of the request call.

This method takes the following arguments.

Method argument	Null?	Description
requestContext	No	A RequestContext object that contains information about this request. See class RequestContext for useful properties on this object.
elapsedMs	No	The total number of milliseconds (as a primitive long value) that it took for PolicyCenter to execute any of the other IRestDispatchPlugin plugin methods as well as the API call itself.
handlerResponse	Yes	The response from the API handler.
operationError	Yes	An ErrorInfo object generated from determining and then executing the request operation handler.
serializedResponse	Yes	Any serialized content returned as the response of the operation handler.
serializationError	Yes	An ErrorInfo object generated by the serialization process.
writeException	Yes	An ErrorInfo object generated by an exception in the write operation. Typically, this is a IO exception at this stage of the request.

The set of arguments for the handleRequestProcessed method depends on whether the request succeeded or whether the request threw an exception during the processing, serialization, or writing of the response. The following list describes the overall control flow of a REST request.

Process flow	Possible actions
Perform initial set up of request: Determine operation handler Perform user authentication Check permissions	If an error at this stage, the method does the following: It populates the operationError argument. It sets the values of handlerResponse, serializationResponse, and serializationError to null.
Invoke the operation handler	If successful, the operation handler returns the handlerResponse argument. If an error occurs at this stage, the method does the following: It populates the operationError argument. It sets the values of handlerResponse, serializationResponse, and serializationError to null.
Serialize the operation result	The method serializes the result returned in the handlerResponse argument and stores the serialization in method argument serializedResponse. If an error occurs at this stage, the method does the following: It populates the serializationError argument. It sets the value of serializationResponse to null
Write the response to the output stream	As the final step in the REST request processing flow, PolicyCenter writes one of the following to the output stream in serialized form: serializedResponse errorInfo If an error occurs at this stage, the method does the following: It populates writeException argument with the error information.

Thus, by looking at the values of the arguments for this method, you can reconstruct whether PolicyCenter successfully processed the request. For example, if the request failed, you can determine whether the request failed because of a client error (such as bad input or a resource that does not exist) or a server error (such as improper operation of the request handler or the handler returned invalid output). You can also determine whether the error occurred during request handling, during the attempt to serialize the handler response, or while writing the serialized response to the output stream.