5.1.3. Operation and variant description: reading guide

This chapter is a reading guide to the detailed descriptions of all variants applicable for a cluster/operation combination. A general overview of the API-framework is available in Overview of the API-framework. You can find a detailed overview of all functions in Overview of all functions.

The chapters starting from Claim describe the different operations and applicable variants for each cluster, in combination with the AFD structure it is connected to. In order to make the description more comprehensible, all these sections use a similar structure. The structure of these sections will be explained in this chapter.

Operation: [name of the operation]

Under the header Operation, you can find a general description of the specific operation. Each operation (e.g. new, change, retrieve) of a cluster is explained in a separate chapter. A general explanation of operations is available in the Overview of the API-framework.

How to use variants

Here you can find a short description of the selection of a variant for an operation and the consequences for the request and the response.

Variants

An overview of all variants applicable for this operation is shown in a table including a short description of each variant. The last column defines whether the variant applies to the related AFD structure. A general explanation of operations is available in the Overview of the API-framework.

Below the table with all applicable variants, each variant is shown as a collapsible.

variant – [Name of the variant]

The variant within the operation is explained in the header section of the variant.

Endpoint and AFD Structure

Each AFD structure which can be used within the operation and variant is explained.

The API endpoint and the technical operation (POST, PUT, PATCH, GET) are given with the request and response.

The { uri } consists of a number of parts:

• the url of the website of the website of the organization
• the applicable product
• version number
  

In case of breakable (non-backward compatible) versions the version number is raised. In cases of non-breakable (backward compatible) versions, the versioning can be part of the header parameters. In Design principles you can find extra information about breakable vs. non-breakable versions.

Example:

https://www.sivi.org/api/varh/v1/policies/new

A table with the mandatory input and/or output attributes is shown.

Mandatory input and/or output (I/O) attributes:

Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.