REST API building blocks

The Guidewire REST API framework uses the following types of files to define the API contract:
  • Swagger 2.0 schema files to define the structure of a given API
  • JSON schema files to define the schema for API inputs and outputs

Together, the defined Swagger and JSON schema file determine the following parts of the REST API.

API resources
Swagger files define the set of endpoint resources exposed by the API. Each resource is called a "path" or "path item" in Swagger, and can have variables interposed for things such as resource IDs. For example, the following string can define a resource for the addresses associated with a specific user:
  • /users/{contactId}/addresses
In this example, /users and /addresses are Swagger path items.
HTTP verbs
Swagger files define the set of HTTP verbs it is possible to use to operate on a particular resource. Swagger calls these verbs the API "operations." For example:
  • A GET operation on /users/{userId}/addresses returns the addresses for the specified user.
  • A POST operation on /users/{userId}/addresses adds a new address to the specified user.
  • A PATCH operation on /users/{userId}/addresses/{addressId} updates existing information on the specified user/address.
  • A DELETE operation on /users/{userId}/addresses/{addressId} deletes the specified user/address.
Payload schema
JSON files define the schema for the payload (the body of the request) that the API passes during request, if any. In the previous example, a POST operation to resource /users/{userId}/addresses can specify a JSON schema definition that defines the format for the body of the POST request.
Response schema
JSON files define the schema for the response returned by an operation, if any, as well as any possible HTTP codes that the operation returns. For example, a GET request to resource /users/{userId}/addresses can specify a JSON schema for the list of addresses and that the default success code is 200.
Path and custom headers
Swagger files define the set of path parameters and custom headers that are applicable to each operation. In the previous example, {userId} and {addressId} are path parameters. At runtime, the REST API framework matches the request URL against the defined path and extracts out those path parameters for use by the application code.
Validation and serialization/deserialization
Swagger files define the validation and serialization/deserialization process for API parameters, and API inputs and outputs. For example, it is possible to declare a parameter as required, or with a specified minimum and maximum value, or as an integer rather than a string. The REST API framework can then use that information to automatically validate the inputs and return an appropriate HTTP response if the input is invalid, and can deserialize the data into appropriate POJOs for use by the application code

Each operation defined within the Swagger schema binds to a specific handler class and method. The REST API framework then uses that class method to process the request whenever a request is made against the appropriate URL and HTTP method.