5.2. Overview of all functions

Introduction

The SIVI API-framework function overview contains two documents. One document is based on the Category Functional and contains all the functional functions of this framework. The other document is based on the Category Technical and contains all the technical functions of this framework. Each row in the document describes a complete API function. Every API function is divided in a Function section and an API Definition section.

Function

The Function section shows the functional part of the API function and contains the following components:

• Cluster – group of functions with the same scope (see Overview of the API framework).
• Operation – the different operations of a function (see Overview of the API framework).
• Variant – the different variants of an operation (see Overview of the API framework).
• AFD structure – the specific dataset to which the API function applies (see chapter AFD structures).
• Meaning – description of the API operation.
  

API Definition

The API Definition section shows the technical part of the API function and contains the following components:

• Method – API operations (see Design principles):
  • POST – add a new dataset to the collection.
  • PUT – replace the whole dataset.
  • PATCH – replace a partial dataset.
  • GET – retrieve a dataset via HTTP parameters.
• Path/Endpoint – Composition of the following elements:
  • The data set of the AFD structure.
  • If a specific subdataset is applicable, this is added to the endpoint, as well. If a specific ‘id’ of the requested data set is applicable, the ‘id’ of that data set is added here as a path parameter, for example /policies/{policyId}/change. If a second ‘id’ applies, the ‘id’of that subdata set is added here as a path parameter, as well, for example /master-agreements/{masterAgreementId}/contracts/{contractId}/change.
  • Variant
    • If the variant is equal to default, the endpoint ends with the operation.
    • In other cases the endpoint ends with the applicable variant and the operation is omitted, unless omitting the operation makes the endpoint non-unique.
    • In cases of variant ‘rate’, the endpoint does not end with the variant, but with the operation, for example /policies/{policyId}/rates/change.
• Request – the payload is included in the body of the request message and contains the business information (see Design principles).
• Query parameter – query parameters are key value pairs that are appended to the URL of a resource.
• Response – the output section is a functional description of the content of the response (see Design principles).
  

See for a more in depth explanation of path parameters and query parameters the Design principles.

Functional functions

All functions included in de SIVI API-framework in the functional category are listed below. A more detailed explanation of these functions will follow in the remainder of this chapter.

Technical functions

All functions included in de SIVI API-framework in the technical category are listed below. A more detailed explanation of these functions will follow in chapter Technical functions.

Changes in API-framework

The new design of the API-framework has major advantages. For example, by connecting the functions to the AFD structures, the API-framework has become more consistent and flexible. As a result, the usage possibilities have grown and the API framework is now applicable across the financial domain. Finally, the structure of endpoints is more logical than before. Each single endpoint is used only once.

Example: in the existing API-framework the functions changeOffer (in case of a correction) and retrieveOffer use the same endpoint (/policy-offers/{offerId}). In the new API-framework they use different endpoints (/policies/offers/{offerId}/correction and /policies/offers/{offerId}/retrieve).

Due to these adjustments, several endpoints have changed. In the table below you can find an overview of the new endpoints mapped to the existing endpoints with the same functional meaning.