Introduction
The All Finance API-framework describes API functionality as much as possible in general terms. Where technical context is relevant or needed the REST design principles are used. REST is a set of architectural constraints, not a protocol or a standard. In this way, the All Finance API-framework is in line with mainstream web development.
API-operations
An API-operation is an operation that is performed by using a set of data. Many API applications focus mainly on retrieving data; music, images, videos, text. In that context it makes sense to use the dataset angle to group and present the API-operations. 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.
An API-operation is always related to one or more AFD structures. The definition of the available AFD structures is described in the chapter AFD structures. An overview of the correlation between AFD structures and API-operations is included in the Overview of the API-framework. In the Overview of all functions you can find all available functions, including their endpoints and the methods they use.
Depending on the API-operation the following classes are available:
- Submit
- Change
- Delete
- Retrieve
Submit operations
A submit operation (POST method) is designed to add a new dataset to the collection, for example a new offer, policy or claim. The purpose of a submit operation is to add a record to the system or record which is exposed through the API.
There is also a set of API-operations that behaves like a submit action, but the purpose is not to deliver a new dataset for the system or record. Instead, the dataset is delivered to the server in order to obtain data in return, for instance to calculate a rate, underwrite a policy or initiate a process. The main objective of these API-operations is to execute a procedure in order to obtain a result. From a functional point of view these operations focus on retrieval; they aim to get a premium amount, an underwriting result or a deeplink to start a dialog. A retrieve function has no body section and cannot contain input data. It only contains an id or query as parameters to get one or more existing datasets. Because of the restriction of the retrieve operation to carry data input, these procedural operations must behave like a submit operation.
Change operations
An update (or change) operation can be implemented in two ways, similar to the HTTP PUT and PATCH methods.
It is possible to do a minor change by replacing all attributes of the entity, both changed and unchanged (the PUT method). A complete replacement is relatively easy to implement, and is therefore considered the minimum requirement for an update function.
This easy implementation comes at a cost, however. The PUT method requires all relevant data to be available during the whole process. But that is not always possible. Offering a PATCH option is a way to avoid this, because a PATCH method can handle partial updates. It is up to the party proposing the API whether or not to include this PATCH option.
Delete operations
In a straightforward implementation the HTTP method DELETE is used to terminate an entity. But financial products are often subject to regulations that impose rules on the time period certain information (like advice, offer and policy) should be available for audit purposes, the mandatory retention period. As a result, termination of an entity is usually treated as a change of that entity, earmarking it with a special status (like terminated or deleted). The actual deletion after a mandatory retention period is considered an internal process and falls outside the scope of the API-framework.
Retrieve operations
The retrieve operation returns dynamic data which depends on input from the API consumer. An API can receive input via the HTTP body and via the HTTP parameters. The HTTP GET method doesn’t have a body and will be provided with input via HTTP parameters. There are three HTTP parameter types for the GET method within AFS, namely path parameters, query parameters and header parameters. For the GET Method the use of form parameters is not supported in SIVI AFS.
Versioning
There are two types of versioning: breakable and non-breakable. Breakable versions are not backward compatible: the message and/or parameters have been modified in such a way that a call by a previous version will not work. This version becomes part of the URL and thus becomes a new URL. The supplier can decide whether the previous version will continue to exist temporarily or not. If a version is no longer supported and the URL has been removed, any call to this URL is returned with an HTTP status 404.
A non-breakable version is backward compatible. This version is added as header parameter and can be used to use the functionality of that version. If a previous version was added as header parameter, that version will be used, until it will not be available anymore. In that case the next available version will be used. If no version is added as header parameter, then, by default, the current version is used.
Parameters
Path parameters
A URL path is used to identify a resource. A path parameter is part of the URL and thus becomes part of the resource identifier. Path parameters are thus locators. Multiple path parameters are possible, but always from a tree structure. Hierarchies can be well expressed by path parameters, but lists not. Lists use a query parameter.
/policies/{ policyId }If a path parameter is invalid or missing, the URL becomes invalid, as it does not identify a resource. As a result, the resource cannot be found, and the status code 404 Not Found is returned.
Query parameters
Query parameters are key value pairs that are appended to the URL of a resource. Multiple query parameters can be concatenated, forming a list.
The parameter _filter is used to compose and pass a filter. This parameter is composed of an array of attributes completed with the operator and its value. The attribute name is written out here with the entity and entity type, each separated by a period. The operator (in this case |eq|, meaning equal) comes after the attribute, followed by the value of that attribute.
Example: _filter=party.policyHolder.surname|eq|Jansen,party.policyHolder.city|eq|Utrecht
| Operator | Explanation | Example |
| attribute|eq|x | Equal. | surname|eq|Jansen |
| attribute|ne|x | Not equal. | surname|ne|jansen |
| attribute|lt|x | Less than. | houseNumber|lt|10 |
| attribute|le|x | Less than or equal. | houseNumber|le|10 |
| attribute|gt|x | Greater than. | houseNumber|gt|10 |
| attribute|ge|x | Greater than or equal. | houseNumber|ge|10 |
| attribute|like|x | Test part of the value. Value with wildcards (* and ?). | surname|like|jansen (exact) surname|like|?ansen surname|like|jans* |
| attribute|in|x;y;… | Value is in list of values. | name|in|jansen;pietersen |
| attribute|contains|x;y;… | Array attribute must contain given elements (x;y;…). | multipleNationalities|contains|0001;0131 |
| attribute|isnull|true | Value of the attribute is NULL. The options are true or false. | |
| attribute|isempty|true | Value of the attribute is NULL or empty. The options are true or false. |
| Which fields to receive | Remarks |
| _fields=attribute1,attribute2 | Only the given fields will be returned. |
| _fields=-attribute1,-attribute2 | Minus sign excludes the given field(s), all other fields will be returned. |
| Sort the result | Remarks |
| _sort=attribute1,attribute2,… | |
| _sort=-attribute1,-attribute2,… | Minus sign sorts the given attribute descending. |
| Timetravel | Remarks |
| validOn=yyyy-mm-dd | Valid on -> Valid on the given date. |
| Pagination | Remarks |
| limit=x | Limit the response to x items. |
| offset=x | Start the limited response from item x. |
Note that paging requires an implied ordering. By default this may be the item’s unique identifier, but can be other ordered fields such as a created date.
Never use sensitive data in the query string parameters that you do not want others to be able to log/view/use. In such cases (e.g. privacy sensitive customer data) use the payload of the messages.
In SIVI AFS APIs, query parameters are designed as optional inputs for the API. If a query parameter is not present, the API should function without them. If a query parameter is an invalid identifier, the status code 400 Bad Request is returned. If a query parameter is a valid identifier, but the underlying resource cannot be found, the status code 204 No Content is returned.
Example use of query parameters:
...SIVI_API_Framework/ExampleCarInsurance/1.0.0/policies/list?_fields=party.policyHolder.relationNumber,party.policyHolder.surname,party.policyHolder.initials,party.policyHolder.prefixes&_filter=party.policyHolder.surname|eq|Velden&_filter=party.policyHolder.city|eq|UtrechtHeader parameters
Header parameters are key-value pairs, where the key is the name of the HTTP header and the value is the parameter value. Header parameters are sent in the HTTP header. They can be used in both requests and responses.
Typically, header parameters are used for metadata. Header parameters provide information on how to process the request or response without having to analyse the payload in the HTTP body.
Accept: application/json; version=1In SIVI AFS HTTP headers are standardised HTTP headers. Custom HTTP headers are not supported in SIVI AFS. If parties want to process custom parameters they can use query parameters instead of custom HTTP headers.
See for all standard HTTP headers: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers.
Depending on the function and variant, a path or query parameter, or combination of both is supported. A description of supported parameters and information on how to use them can be found in the chapters of the individual functions.
Input specification
Except for the GET method, the input section contains a table with the minimum set of entities and attributes needed in the request body to execute the function.
Payload
The payload of a webservice is included in the body of the request or response message and contains the business information.
Types
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 etc,, 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.
Payload structure
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.
Output specification
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 minimum 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 HTTP 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 (such as calculate rate or underwrite policy) will return a response with a body section.
- Functions which submit or change a dataset will receive a response if the transaction is successful. The response message does not require a body section, but in order to simplify processing it is advised that the input data is returned in the output for reference and 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.
Feedback
Powered by
Post your comment on this topic.