5.10. Swagger examples of domain specific functions

The SIVI AFS API framework and the overview of functions are the starting point for opening up APIs to the market. In this section we describe how this framework works, using some examples in SwaggerHub. By clicking the green button below, the user gets access to these examples.
The purpose of these examples is to give more insight in the complete process of the request and response in a specific case. The examples do not describe all possible functions, but they focus on functions related to insurance policies.

The combination of category, cluster, operation and variant determines the applicable function. The category used in the examples is functional. Example: selecting the cluster contract, combined with operation new and variant default, results in a request for a new contract. Because this request is an application for a new insurance, the policyStructure is used to add a new policy.

Introduction to the examples in SwaggerHub

The examples are created around the API methods applied within the SIVI AFS API-framework: POST, PUT, PATCH and GET. These API methods are related to the following three SIVI AFS operations: new, change and retrieve.

Each example is structured as follows:

• The name of the SIVI AFS operation (e.g. new).
• The name of the API method (e.g. POST).
• The endpoint: this gives information about the variant used.
• Parameters (not applicable in case of POST).
• Request body (not applicable in case of GET).
• Possible responses.
  

Because the examples in SwaggerHub are static, all possible responses are shown there. For example, a technically correct message results in an HTTP return code of 200.

New

The operation new in the examples describes a new insurance. More variants are possible within this operation. Two variants of this operation are described in the SwaggerHub examples: a default and a rate.

Since this is the request for a new policy, the API method POST is used.

The standard variant (with end point /policies/new) describes a new insurance application. The rate variant (with endpoint/policies/rates/application) describes a premium calculation for a new policy.

Change

In these examples, the operation change involves changes to an existing insurance policy. There are two ways to pass on a change: completely or partially. Two different API methods are available for this: PUT and PATCH.

The API method PUT is used for a complete replacement of the policy with a new version. This is especially applicable, if the change causes a premium adjustment. The PATCH API method is used to make a partial change on a policy. This is applicable if it is a smaller, change, that does not affect the premium. For example, an updated bank account number.

The following variants are used in the examples: correction and detail. The correction variant (with endpoint /policies/{policyId}/correction) is used to replace the entire policy with a new version due to incorrect input. These changes result in a premium adjustment. The API method used in this case is PUT.

The detail variant (with endpoint /policies/{policyId}/detail) is used for a limited change on the policy. For example, a changed bank account number. The API method used in this case is PATCH.

Retrieve

In these examples, the operation retrieve refers to the retrieval of data. A body is not included in the request. The response message does contain a body. The API method available for this operation is GET.

The default variant (with endpoint /policies/{policyId}/retrieve) involves the retrieval of data of a single policy, using a unique reference.

The variant list (with endpoint /policies/list) is applied to retrieve a list of policies, using the contract number by default. It is also possible to extend this attribute with other ones.

Examples in SwaggerHub

By clicking the green button below, the user gets access to the examples in Swaggerhub.

A call to these examples can also be made from other applications (for example soapUI or Postman). The endpoint can be composed from the URI https://virtserver.swaggerhub.com/SIVI_API_Framework/ExampleCarInsurance/1.0.0 supplemented with the requested operation and variant. These examples are available in SwaggerHub. In this case, a technically correct message will be returned.

Examples of return codes and errors

In case of a technically correct message, an HTTP return code 200 is provided and this code is also returned when executing the examples mentioned before. A separate SwaggerHub page makes it possible to call examples of other return codes. The endpoint to this page is composed of the URI https://virtserver.swaggerhub.com/SIVI_API_Framework/ExampleCarInsurance/1.0, supplemented with the requested return code (e.g. .204, .400) and the desired endpoint. This is the same call as the examples above, only with the return code within the url (e.g. https://virtserver.swaggerhub.com/SIVI_API_Framework/ExampleCarInsurance/1.0.400/policies/new).

Availablity of examples:

In case of an HTTP return code 401 the following endpoints can be used:

• https://virtserver.swaggerhub.com/SIVI_API_Framework/ExampleCarInsurance/1.0.401/policies/new
• https://virtserver.swaggerhub.com/SIVI_API_Framework/ExampleCarInsurance/1.0.401/policies/rates/application
• https://virtserver.swaggerhub.com/SIVI_API_Framework/ExampleCarInsurance/1.0.401/policies/pp0202168/change
• https://virtserver.swaggerhub.com/SIVI_API_Framework/ExampleCarInsurance/1.0.401/policies/pp0202168/detail
• https://virtserver.swaggerhub.com/SIVI_API_Framework/ExampleCarInsurance/1.0.401/policies/pp0202168/retrieve
• https://virtserver.swaggerhub.com/SIVI_API_Framework/ExampleCarInsurance/1.0.401/policies/list

The (error) messages can be tested in soapUI. Create a project in soapUI:

soapUI Project

You can create a request, but this is not absolutely necessary:

soapUI Request

Specify the appropriate method for the endpoint in question:

soapUI Method

With the endpoint and resource it is possible to indicate, whether the request was good or bad:

soapUI URL

If you fill in the request correctly, you will receive a response after running the request:

soapUI Response