Designing a REST API

In designing a REST API, your first task is to determine the following:
  • The structure of the API resources
  • The HTTP verbs to make available
  • The structure of the API inputs and outputs

API definition tasks

The actual definition of the API consists of the following two tasks:
  1. Create a schema.json file to define the structure of any JSON inputs and outputs.
  2. Create a swagger.yaml file that defines the API paths (endpoints) and operations.

Guidewire recommendations

In general, Guidewire recommends that you use the following conventions in designing a REST API:
  1. Try to structure actions as operations on resources rather than as RPC calls. This means that instead of calling an addContact method, you perform a POST operation to a /contacts resource. However, not all API actions fit nicely within the standard HTTP verbs.
  2. Do not try to mutate (change) a resource using a GET operation.
  3. Use the following HTTP verbs to perform actions on a resource:
    • GET to retrieve an existing resource or resources
    • PATCH to partially update a resource, updating specific fields, for example
    • DELETE to remove objects
    • POST to create new resources under an existing container
  4. Use plurals for resource paths in which there are multiple sub-resources. For example, if there are multiple contacts, use /contacts/{contactId} rather than /contact/{contactId}.