7. Proprietary APIs

The objective of the SIVI AFS API-framework is to provide a blueprint for generic functions that are used in the value chain of financial products. This enables parties to model their APIs in a standard format which is recognizable throughout the industry and facilitates software architectures and implementations. A party that provides an API for the market can take one or more function(s) from the SIVI AFS API-framework, add all necessary details, and tailor it to company specific requirements, all within the AFS standard formats of function (API-framework) and content (AFD 2.0).

In this example, an insurer wants to offer an API when renewing its Business Non-Life Product for liability (Business Liability Flex). It is not necessary to implement all functions of the API-framework. The table below shows some examples of API-functions.
You select functions that, for example, are commercially (sales opportunities) and operationally (cost savings) interesting. A precondition such as the system infrastructure can potentially be a limiting factor. For example: a real-time web service for data retrieval is less obvious, if the product is administered in a less accessible application. But you also make an assessment based on the type of business operations of the users of the API. Example: is the user an authorized agent or a large provincial agent? For each type of business you then list the software that will use this API. Are specific interfaces used (as VPI) or is the software adapted specifically for the use of this API?

Target group: in this column we define the user groups who will implement the API for this product. In this case, the intention is to set up chain wide support. The support of small provincial offices is primarily set up through the extranet (not in this table). But within customer folders that are in use, users would like to support consultation of a policy. Apart from that, it is important that the advice and comparison software can calculate an indicative premium. The insurer is working with a number of large intermediary organizations who want to work provincially, but want to include support for the product in the self-established purchase line (Mid office) and within a website where a customer can buy his own insurance (Customer folder). For authorized agents (MGA) the insurer will connect the API to the VPI-platform. Two functions are provided: premium calculation and underwriting.

Target software: it is important to understand sufficiently what type of software is going to use the API-services. This plays a role for the features the functions should provide and for the composition of the shortlist of providers that should know about the existence of the API. It may also be advisable to make agreements with specific suppliers around implementation. The advantage of following standards is that the software is generic in nature. In this way, customization for specific parties can be avoided as much as possible. The table above contains generic names. Of course, it is also possible to put the names of specific suppliers and environments. That makes the insight even more realistic. The Overview software and services Financial Services contains an up-to-date overview.

API functions: select the applicable functions from the API-framework. It is possible that not all required functions may fit within the SIVI AFS API framework. Sometimes there is no other option than to implement a proprietary function. A proprietary function can also be SIVI AFS compliant. An API can be developed according to the general guidelines and the use of the AFD datacatalog.

It is important to stay as close as possible to the benefits of standardized data exchange within the SIVI AFS API-framework. For this purpose, guidelines have been developed, to which all functions within the SIVI AFS API-framework comply. An organization can also use these guidelines to develop proprietary APIs. This ensures that a proprietary API matches the design criteria and that it properly uses AFD structures and the AFD model. Note that it is also possible to submit requests for entities, attributes and code lists in case of proprietary APIs. If SIVI cannot fulfill these requests, it is also possible to use the customAttribute construction to add proprietary attributes in a generic way.

The impact assessment of connection to the SIVI API framework will take a number of iterations. SIVI is happy to provide guidance in this process. You can contact SIVI at support@sivi.org.

When to use proprietary APIs

The examples below show situations, where proprietary APIs can be used.

Example 1
The supplier offers a service for risk analysis of work equipment. A number of web services allow the user to query this analysis in steps. The function calls and attributes are so service-specific that they do not fit into the SIVI AFS API framework.

Example 2
An insurer wants to develop a web service for application for absenteeism insurance. The policy information is located in another system than the information and substantiation of the wage sum to be insured. Systemically, a short-term request must be distributed over two services (endpoints). This is a variant for the operation new contract that is so situation-specific that it does not fit into the SIVI AFS API framework.

API function

General

• All API specifications are based on the REST architecture
• Following OAS 3.0 or higher
• Based on AFD 2.0 building blocks and AFD structures

Namespace

• Endpoint parameters are written in camelCase (starting with lower case) e.g. policyId.
• The API name corresponds with the name of the cluster as described in chapter Domain Specific Functions in this manual (e.g. Claim).
• Endpoints refer to resources as nouns, not verbs.
• An API endpoint represents a collection of resources, a subset, or a single resource from the collection.
• API endpoints start with a plural form, e.g. /policies/ (collection of all policies).
• API endpoints may end in a singular form, e.g. /policies/{policyId}/change (operation change for a specified policy).
• Compound words in API endpoints use a hyphen between the words. e.g. /policies/{policyId}/ termination-with-surrender.
• API endpoints are used to execute one of the following HTTP operations:
  • POST: submit a new resource to the collection (e.g. policy)
  • PUT: replace the complete data set of a resource
  • PATCH: replace or add part of the dataset of a resource (e.g. a new value for the status attribute)
  • GET: retrieve resource information
• Endpoints for an API PATCH operation may contain a variant at the end to indicate the reason or purpose of the patch action, using the variants as described in this manual, e.g.:
  • /policies/{policyId}/agent
  • /policies/{policyId}/detail
  • /policies/{policyId}/status
• API POST and PUT endpoints may have a variant at the end, indicating a specific type of creation or change, e.g.:
  • POST /policies/offer
  • POST /policies/offers/{offerId}/based-on-offer
  • POST /policies/notification
  • POST /policies/special-limits/registration
  • POST /claims/registration
  • PUT /policies/{policyId}/correction
  • PUT /policies/{policyId}/offer
  • PUT /claims/{claimId}/correction

Parameter or payload may contain the following kind of information:

• AFD Structures.
• The request body for POST, PUT and PATCH endpoints always use a payload in an AFD structure. This also applies to the response body, if applicable.
• Endpoints used by a GET operation may have a request body (but this is not mandatory).
• Endpoints for PUT and PATCH use a path parameter to identify the resource, e.g.:
  • PUT /policies/ {policyId} /…
  • PATCH /policies/ {policyId} /detail
• The body of a PATCH request is kept as compact as possible, only required and relevant attributes are used.
• Query parameters are key value pairs that are appended to the URL of a resource. More information on query parameters is available in Design principles.
  

Response

More information on response messages is available in Design principles.

Security token

Depending on the sensitivity of the data, the API must be secured according to best practices for REST APIs and company specific policies. The implementing party is responsible for the security of the environment.

• Authentication should only be used over HTTPS (SSL).
• Minimum requirement for secure data is Bearer authentication (also called token authentication), the HTTP authentication scheme that involves security (bearer) tokens.
• Recommended security is OAuth (2.0), using an access token, and optionally a refresh token.