The SIVI All Finance API-framework is designed to support business processes within the financial services industry. While developing the API-framework, the following main design principles are adopted.
The hierarchy of function group, function and variant is used to cover all aspects of the business processes and workflows:
The API-framework function hierarchy has been drawn up in line with processes within the distribution chain and is designed to support four domains (see also figure 7-1 above). With this, the API-framework supports an important part of the work areas within financial services. The function hierarchy can be divided into three categories, based on the purpose for which they are intended:
- Function groups: functions are grouped around application areas like premium calculation, underwriting or claim handling. These areas use the same AFD structures (see also AFD structures) and core datasets.
- Functions: the individual functions describe the requested adaptations and contain the basic functions to submit, change and retrieve data for the applicable situations. These are the standard adaptations that are part of the CRUD (create/retrieve/update/delete).
- Variants: the function variant enables more specific detailing of a base function with regard to the required data. For example, the dataset for a quick quote will be much smaller than the dataset for a formal request or a policy application.
The All Finance API-framework describes API functionality as much as possible in general terms. But given the fact that modern API’s are based on REST architecture, the RESTfull approach which uses standard HTTP functionality has been used. This has some consequences with regard to the use of parameters and the definition of the payload.
AFD structures and payload
A single function may use different structures for the same functional purpose. For example the calculation of a premium for an insurance policy, or for a pension. On the other hand, a single structure can be used by different functions. For instance the
policyStructure which is used to calculate premium, submit an offer or change a policy.
The combinations of functions and data structures could be regarded as a matrix like this example:
The function(group) is the most important angle to look for functions, and the Function overview shows the available combinations of function groups and AFD structures.
An API-function is an operation that is performed by using a set of data. Many API applications are mainly focused on retrieving data; music, images, videos, text. In that context it makes sense to use the dataset angle to group and present the API-functions. The SIVI All Finance API-framework, however, is designed to support business processes. Therefore functions are grouped around functional concepts like premium calculation, underwriting, claim handling, etc.
A function is always related to one or more AFD structures. The definition of the available data structures is described in the chapter AFD structures. An overview of the correlation between AFD structures and functions is included in the Function overview chapter.
With respect to the type of operation of functions the following classes are distinguished:
A submit function is designed to add a new dataset to the collection, for example a new offer, policy or claim. The purpose of a submit function is to add a record to the system of record which is exposed through the API.
There is also a category of functions that behaves like a submit action, but the purpose is not to deliver a new dataset for the system of record. Instead, the dataset is delivered to the server in order to obtain data in return, for instance calculatePremium, underwritePolicy or initiateProcess. The main objective of these functions is to execute a procedure in order to obtain a result.
From a functional point of view these functions focus on retrieval; they aim to get a premium amount, an underwriting result or a deeplink to start a dialog.
Note that, in order to obtain the required result, input data must be submitted. A retrieve function has no body section and cannot contain input data. It only contains an id or query in the header parameters to get one or more existing datasets. Because of the restriction of the retrieve function to carry data input, these procedural functions must behave like a submit function.
Because procedural functions work in a different way, they have a different kind of function name to set them apart; instead of ‘submit’ these functions use a different verb (e.g. calculate, underwrite, initiate).
An update function can be implemented in two ways, similar to the HTTP PUT and PATCH methods.
Even a minor change can of course be done by replacing all attributes of the entity, both changed and unchanged. A complete replacement is relatively easy to implement, and is therefore considered the minimal requirement for an update function.
The cost of the easy implementation of the PUT variant, is the requirement to deliver all the relevant data which may in certain steps of the process not always be possible.
Offering a PATCH option is a way to avoid this. It is left to the party that proposes the API whether or not to include the option.
In a straightforward implementation the HTTP method DELETE is used when an entity is terminated. But with financial products there are often regulations which impose a defined period over which certain information (advice, offer, policy) needs to be preserved for audit purposes. As a result, the termination is usually handled as a change of the entity to earmark it with a special status. The actual deletion after a mandatory retention period is considered an internal process and falls outside the scope of the API-framework.
The retrieve function uses the HTTP GET method with optional parameters in the request header to define a single dataset or a query that can result in multiple datasets.
There are options defined for the retrieval of a full dataset for a single item, the status of an item, a full dataset of a range of items, and a reference list of all available items.
These can be implemented by using the standard HTTP header options for API requests. In addition, the ‘Select’ parameter can be used to specify which attributes should be returned in the response.
singlevariant uses the path parameter with the id for a single dataset. The id is embedded in the uri and points straight to the individual dataset.
This retrieves the full dataset, unless the ‘Select’ parameter is used to receive only a subset of the data, for instance the
statusvariant is identical to the
singlevariant, but with the addition of the ‘Select’ parameter to receive only the
rangevariant uses the query parameter to provide a set of id’s. This can be done in different ways, the style keyword defines how multiple values are delimited, according to the serialization rules of the OpenAPI 3.0.0 specification.
listvariant retrieves the reference attributes for each dataset as defined by the ‘Select’ parameter.
The input section contains a table with the minimal set of entities and attributes needed in the request body to execute the function. The input section can be divided into parameters and payload, see below.
Parameters can be divided into technical and functional parameters.
Technical parameters are used for communication and security, for instance the header fields Authorization and Content-Type.
They can also be used to define part of the url (path:) or to make a selection by adding a query string. These parameters are present in the HTTP header fields or in the url.
Functional parameters are included in the message body and are part of the payload, like the
functionVariant parameter for example. They can be used to direct downstream handling of the message content towards specific processes or workflows.
The payload of a webservice is contained in the body of the request or response message and contains the business information.
The payload can consist of any type or form of information, for instance:
- Structured data in JSON or XML notation.
- Binary files containing images and/or sound.
- Any current document type like Microsoft Word, Excel, Powerpoint and so on, or their open source equivalents.
- Files in other proprietary application formats like pdf.
The last three options must always be encoded in order to be passed on as a text string in the message body, for example by converting it into base64.
The payload is always defined with AFD attributes within an AFD structure. As mentioned in the previous section, the payload can also contain functional parameters.
The AFD structure offers all available entities with their attributes, depending on the function and/or variant. A subset can be defined in the API specification to detail specific required and optional attributes..
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, et cetera) with an attachment included.
- A response body with an AFD structure containing a partial or full dataset.
In REST API implementations the first type is the most common, using the standard HTTP status codes. Details can be found in the section Status codes and error handling.
Whether a response has a mandatory or optional body section depends on the type of function:
- Functions that execute a server process (calculate premium, underwrite policy, initiate process) will return a response with a body section.
- Functions which submit or change a dataset will receive a response (with a HTTP status code 2xx) when the request has been successfully handled by the server, see also Status codes. The response status code can be logged for internal use, like process control or audit purposes. The response message does not require a body section, but one may be added to provide additional information.
- Retrieve functions will always return a response with a body section.
The situations described above are based on valid requests that could be processed successfully. If the request could not be handled properly, the response will be different. These situations are described separately in the error section.