Handler method parameters

Each parameter to the API handler method must be one of the following:
  • A RequestContext object
  • A parameter declared on the Swagger schema for the associated operation

Guidewire does not require that a handler method have a method parameter for every possible operation parameter. The REST framework can retrieve operation parameter values at runtime by name from the runtime RequestContext object if there are no explicit arguments to the handler method.

Parameters of type RequestContext

If the method parameter is of type RequestContext (regardless of the parameter name), the framework passes in the runtime RequestContext object. The runtime RequestContext object gives the handler method access to information about the runtime context of the request such as the following:

  • The raw HttpServletRequest servlet container object, which can provide raw request information that is not accessible in other ways.
  • Headers and path parameters by name, in either deserialized form (if explicitly listed in the schema) or raw form. This is often helpful if writing common infrastructure shared across multiple API endpoints.
  • The metadata about the request being served such as the SwaggerOperation object, path template, or the fully-qualified name of the request API.
  • The negotiated content type and other context information.

See The RequestContext object for more information.

Other parameter types

All method parameters that are not of type RequestContext must have the following characteristics:
  • The parameter name must match the name of a Swagger operation parameter.
  • The parameter type must match to something the REST framework can deserialize.
For parameters other than the body parameter, the type of the method parameter must match the runtime type of the operation parameter as specified by the following properties:
  • type
  • format
  • x-gw-type

If the parameter defines a set of items, the runtime type becomes a list of such objects (List[objects]).

Parameters of type body

The REST framework treats the body parameter as a special case, as it is possible to deserialize the request body data to many different runtime types. If the operation consumes the application/json media type, and no other types, then the body parameter can be any of the following types:
  • byte[]
  • String
  • JsonObject
  • Any subtype of JsonWrapper (which are generated schema wrapper types)

If the operation consumes multiple media types, or does not consume application/json, then the body parameter can be only of type byte[] or String.

Method return types

A handler method can return any of the following types.
void
If an operation returns a 204 response code, the method handler can have no return value. This indicates that the method has no response payload. In this case, the handler method can have a void return type, If the return type is void, the Swagger operation must not declare any produces type.
String or byte[]
For a return type other than JSON, the handler method can return a String or byte[] array. The REST framework then writes out as the raw string or bytes as the response.
JsonObject or JsonWrapper subtype
An operation that produces JSON-formatted data can return a JsonObject or any generated schema wrapper type. The method serializes the JsonObject object according to the schema (if any) associated with the operation's 2xx response code. For wrapper subtypes, the framework unwraps the wrapper and then serializes the object as JSON.
TransformResult
An operation that produces JSON-formatted date and that uses an Integration Mapping to produce that data can return a TransformResult directly.
Response
If the method handler needs more explicit control over the response's status code, or adds custom headers to the response, the method handler can return a Response object that combines the desired status code, response body, and headers.
Any other scalar type
The method invokes the toString method on the object.