REST API Overview

Succeed Insurance's development team needs to create a new REST API to:

• View a contact
• View a list of contact notes
• Update a contact
• Add a note to a contact

In order to implement that requirement, Succeed Insurance's developers need to understand how to implement a custom REST API.

Learning Objective

The learning objective for this module is to understand the framework for creating a custom REST API.

What is the InsuranceSuite REST framework?

A RESTful API is an application program interface (API) that uses HTTP request to GET, PUT, PATCH, POST, and DELETE data. A RESTful API - also referred to as a RESTful web service - is based on representational state transfer (REST) technology.
For more information about REST APIs in InsuranceSuite, check out this documentation.

REST framework components

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. Swagger is a specification for documenting REST APIs.

HTTP Verbs

Swagger files define a set of REST verbs that are supported by the API. The supported verbs are GET, PUT, PATCH, POST, and DELETE.

PATCH vs PUT

PATCH requests that a set of changes described in the request entity be applied to the resource identified by the Request- URI. (Preferred verb for an update). PUT requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server – the entire entity will be replaced. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI.

Payload schema

Guidewire uses JSON files to define the schema for the payload that the API passes during the request, if any.

Response schema

Response schemas are also defined using JSON files. These files define the response, if any, returned by the operation. Response schemas are defined in Integration Views.

Integration Views

Integration Views produce external views of the Guidewire domain model. They provide schemas and mappings that are explicitly named and versioned. Different versions of the same schema and/or mappings can co-exist. The output format is explicitly designed in the schema. Integration Views define the output schema first and then map the data to that output.

More information about Integration Views can be found here.

Path and custom headers

Swagger files define the set of path parameters and custom headers that are applicable to each operation.

Validation and serialization/deserialization

Swagger files define the validation and serialization/deserialization process for API parameters, and API inputs and outputs.

To read more about the API building blocks, check out this part of the Guidewire Documentation.

Standards

Be sure to read the following SurePath documentation for the standards to use when developing REST APIs.

---