The following diagram illustrates the processing flow for the REST servlet.
The REST processing flow diagram uses the following steps.
Servlet container receives API request
The servlet container handles the first step in the processing chain, before the
servlet container invokes the REST servlet.
Reload configuration if necessary
If the application server is running in development mode:
The REST framework checks every incoming request to determine if any relevant
configuration files have changed since the last request.
The REST framework checks whether a hot swap of Gosu classes has occurred.
For either of these development cases, the REST framework reloads the servlet
configuration before processing the request. Guidewire does not support the reload of
the servlet configuration in a production environment.
Log request
The default implementation class for the IRestDispathPlugin plugin
provides a means to log REST API activity.
Check localization headers
Before processing the API request, the REST framework attempts to set up the current
language and locale based on one of the following:
The values set for custom headers GW-Language and
GW-Locale headers
The value set for the Accept-Language header
Setting the localization for the API request ensures that it is possible to
properly localize the rest of the API request (including any error messages).
Match path
The REST framework determines whether the request URL matches to a defined Swagger
path:
If the framework finds a match, the framework extracts the path parameters.
If the framework does not find a match, the framework returns a '404 Not Found'
status code.
Match HTTP verb
After the framework determines that the path matches, it next determines whether the
HTTP verb used in the API request is one that Guidewire supports for the given
path.
There is a match if the request verb corresponds to a Swagger operation declared
on the path, or, if the verb corresponds to one of the HEAD or
OPTIONS HTTP methods that the framework supports
automatically.
There is no match in all other circumstances. If the framework does not find a
verb match, the framework returns a '405 Method Not Allowed' status code.
Authenticate
The REST framework then authenticates the request, if the endpoint in question
requires authentication. The framework authenticates all Swagger operations by
default, with the exception of the OPTIONS method, which the
framework supports automatically. The framework returns a '401 Unauthorized' response
code if authentication fails for any reason.
In the base configuration, the framework marks as unauthenticated the
/apis endpoint and the /swagger.json paths
that the default development template adds to the API. The framework determines
whether to authenticate HEAD method requests based on whether it
authenticates the corresponding GET request.
It is also possible to specify the x-gw-authentication property on
an operation as false. This setting instructs the framework to
disable authentication for that particular operation.
Check localization preferences
In working with the request localization, the framework only uses any language
preferences set by the user in the following circumstances:
The user must have past authentication.
The API request itself did not specify any GW-Language or
GW-Locale headers.
If both of these conditions are true, the framework sets the language and locale for
the rest of the request handling based on the preferences of the authenticated
user.
Check run level
The REST framework checks the run level of the server against the value set for the
x-gw-runlevel attribute specified on the operation, path, or root
Swagger document.
The framework returns a '503 Service Unavailable' response code if the framework
determines that the current run level of the server is inadequate to service the
request.
Determine response type
The framework determines the response type, if any, based on a process known as
content negotiation. Content negotiation attempts to match the Accept header of the
request with the content types that the API operation knows how to produce. If the
Accept header is present but does not match any of the produced types, the framework
returns a '406 Not Acceptable' response code. If the Accept header is not a valid
comma-separated list of MIME types, the framework returns a '400 Bad Input' response
code.
Validate content type
If the API request contains a request body, then REST framework attempts to match the
Content-Type of the request against the types that the API operation can consume.
The framework returns a '400 Bad Input' response code under either of the following
circumstances:
The request contains a body and the API operation does not accept a request
payload.
The specified Content-Type is not a valid MIME type.
The framework returns a '415 Unsupported Media Type' response code if the specified
Content-Type does not match one of the types the operation can consume.
Authorize user
If the operation passes authentication, and, the operation declares any system
permissions using the x-gw-permissions property, the framework checks
to see if that the user has all of the permissions required by the property. The
framework returns a '403 Forbidden' response code if the authenticated user is missing
any of the required permissions.
Deserialize and validate input
Before passing the request data to the handler method on the operation, the REST
framework validates and deserializes the input values into POJOs (Plain Old Java
Objects).
The framework validates any passed-in parameters according to any validation
constraints defined in the Swagger schema, such as:
Values that are required
Values must not exceed, or fall below, a certain numveric value
Values that follow a pattern
The framework deserializes the input values based on following schema properties:
type
format
x-gw-type
The framework validates and deserializes the input data according to an associated
schema under the following circumstances:
If the API request produces a response of type
application/json
If the 2xx response code for the operation has an associated schema
The framework returns a '400 Bad Input' exception, with details, if any part of
validation or deserialization proces fails.
Construct handler
The REST framework constructs a new instance of the handler class for each API
request.
Invoke handler
If the REST framework deems that the API request is valid, the framework invokes the
handler method for the operation. In terms of error handling:
If the handler method throws an exception that implements the
HasErrorInfo interface, the method uses an
ErrorInfo object to produce the response and determine the
response code.
If an exception does not implement the HasErrorInfo interface,
the method returns a generic '500 Internal Server Error' response code.
Wrap return value
After the handler method completes successfully, the REST framework wraps the method
return value in a Response object:
If the handler method returns a Response object directly, the
framework uses that object. The framework then adding a content type automatically
based on the negotiated response type, if the content type is not already set.
If the handler method returns null (or void) or
some other value, the framework creates a Response object automatically, with a
response code based on the first 2xx response defined on the operation in the
Swagger schema.
If the schema does not define a 2xx responses, it is an error for the handler to
return anything other than a Response object, as otherwise, the
framework does not know what status code to assign to the response.
Serialize response
Before the REST framework can return the data, the framework needs to serialize the
data into to a String or a byte[] object:
If the response code has an associated schema, and the handler methods returns
either a JsonObject or JsonWrapper object, the
framework serializes the data according to the specified schema.
If the framework serializes the data based on the schema, and the handler method
returns data that does not conform to the schema, the framework returns a '500
Internal Server Error' response code. Thus, the framework can return a 500 error if
the handler method declares properties not declared in the schema, or, if the method
sets a value for a property that is not the correct type specified by the
schema.
Writer response
After the REST framework completes the serialization of the output from the request
handler method, the framework writes the output to the request output stream.
Log response
As a final step, the REST framework logs the request and its response after the
framework writes out the response, which prevents the client request from having to wait
on the log action. In the base configuration, the framework logs each API request
automatically with summary information about the path and operation requested, the
response code, and the time taken to service the request.
