All functions are described in a similar way, following a standard theme with recurring items as described below.

Function: [function name]

Short sentence describing the essence of the function

Usage: [function name]

Brief description of relevant details for the usage of the function.

A table containing the available variants of the function, if applicable. The attribute name that holds the variant is called functionVariant, in the text and the column header in the tables this is abbreviated to plain ‘variant’ to facilitate reading.

# Variant Description
Number Name Short sentence describing the essence of the variant.

Technical specifications: [function name]

Input: [function name]

The required method for the function is not part of this functional description. The method is specified in the technical API definition as one of the standard HTTP methods (POST, PUT/PATCH, GET).
The input section contains a table with the minimal set of entities and attributes needed in the request body to execute the function.
The ‘Variant’ column indicates attributes required for specific function variants by their number, or ‘all’ if applicable.

Name Variant Type Description
Dataset structure
commonFunctional Entity for general information with regard to structure, handling and processing.
dataCatalogVersion string The version of the data catalog serves to validate correctness of the input and output data.
functionVariant string The functionVariant is used to determine the additional set of required and optional input and output data
Main entity General information on main entity level.
attribute 1 string Mandatory attribute
attribute string Additional attributes.
entity Additional entities.
attribute 2 string Mandatory attributes
attribute string Additional/optional attributes.

Output: [function name]

The output section is a functional description of the content of the response. Depending on the technical implementation three types of response are possible:

  • A uri to indicate the location of the dataset that has been processed
  • A response body with an AFD structure containing minimal identification information (offer, policy, claim, …) with an attachment included .
  • A response body with an AFD structure containing a partial or full dataset.

The first type is common in REST API implementations which uses the standard HTTP status codes. Details can be found in the section Status codes and error handling.
All types may have a mandatory or optional body section included in the response, depending on the type of function;

  • Functions that execute a server process (calculate premium, underwrite policy, initiate process) will always get a response with a response body (if the process could be executed).
  • Functions which submit or change a dataset do not require a response body, but a body section with a dataset may be added to the response.
  • Retrieve functions will always contain a dataset in the response body when a valid identification is provided, or when the conditions of a query are met for one or more datasets.

When the response message contains a body section, it is described in a table similar to the one for input data.

Name Variant Type Description
Dataset structure
commonFunctional Entity for general information with regard to structure, handling and processing.
dataCatalogVersion string The version of the data catalog serves to validate correctness of the input and output data.
functionVariant string The offer variant is used to determine the additional set of required and optional input and output data
Main entity General information on main entity level.
attribute 1 string Mandatory attribute
attribute string Additional attributes.
entity Additional entities.
attribute 2 string Mandatory attributes
attribute string Additional/optional attributes.

OAS 3.0.0 specification


Link to the corresponding section of the technical function, according to the Open API Specification, on the SIVI SwaggerHub repository.

Feedback

Thanks for your feedback.

Post your comment on this topic.

Post Comment