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.
Variant | Description | [Name AFD structure] |
[name variant] | [Description of the variant for the applicable operation] | Yes |
… | … | … |
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.
Method | Endpoint | Request | Query parameter(s) |
Response | Remarks |
POST / PUT / PATCH / GET | {uri} / <entity> / <variant> | [Name AFD structure] | [Name AFD structure] |
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:
Entity | Attribute | I/O | Remarks |
[name of the entity] | [name of the attribute] | [I, O, or I/O]* | [remarks about this attribute within the variant] |
… | … | … | … |
… | … | … | … |
Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
Post your comment on this topic.