Implementing a REST API

After you design your REST API (and create the necessary Swagger and JSON files), you then need to implement the handler classes and methods that perform the actual work of the API. Implement any API handler classes that you create in Gosu, as method binding relies on the actual names of the method parameters, which Java compilation does not preserve. However, your Gosu class can subsequently delegate to a Java helper, if desired.

Every REST operation ultimately binds to a particular method on a particular class. You bind a class to an operation by naming the necessary class or classes in an x-gw-apihandlers property on the operation, path, or root document. Guidewire recommends that you first attempt to bind the class to the operation, then to the path, and finally to the root document. This means that the REST API framework uses the property definition on the root object only if the operation, then the path, do not specify the property explicitly.

Invocation of the handler class method

The REST framework invokes the method associated with the operation only after it performs the following tasks:

Authenticates the API request
Validates the request
Deserializes the data inputs

If the input is bad at any step along this process, the REST framework does not invoke the handler method.

Constraints on handler classes

There are few constraints for designing an API handler class, except the following:

Each custom handler class must have a no argument constructor as the REST framework instantiates the handler class on every request.
Each method name must match the operationId value of the operation that called the method.
Each method parameter must be of type RequestContext, or, must be based on a parameter defined for the method as configured in the Swagger schema.

Other than these constraints, you can structure a handler class however you like. Guidewire intentionally designs the REST framework to have minimal binding between the handler class and the REST framework.