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 which provides an API for the market can take a 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 addition, situations occur where parties need to provide company specific services that fall outside the scope of SIVI AFS API-framework. These functions can also be SIVI AFS compliant. An API can be developed according to the general guidelines and the use of the AFD datacatalog. For the short term, personal support will be available upon request. In the next few months instructions will be provided in this chapter.

Please contact us at any time for more information.

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

Name space

  • Endpoint parameters are written in camelCase (starting with lower case) e.g. policyId
  • If a prefix or suffix segment is used, it is separated by a hyphen (e.g. submitOrder-lossAdjustment-request).
  • The API name corresponds with the name of the function group as described in chapter 7 of this manual (e.g. Premium, Policy, 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/policy-id (the set of id’s of all policies in the collection.
  • Compound words in API endpoints use a hyphen between the words. e.g. /policies/policy-id.
  • Endpoints for an API PATCH operation may contain a function 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/renewal /policies/policyId/agent /policies/policyId/suspension /policies/policyId/reinstatement /policies/policyId/termination
  • API POST and PUT endpoints may have a variant at the end, indicating a specific type of creation or change: e.g. POST /policies/submissions/underwritten
    POST /policies/submissions/based-on-offer
    POST /policies/submissions/part-of-master-agreement
    POST /policies/submissions/notification-third-party
    POST /policies/submissions/notification-special-limit
    POST /policies/submissions/request-special-limit
  • API endpoints are used to execute one of the following HTTP operations:
    GET: retrieve resource information
    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.

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 response body, if applicable.
  • Endpoints used by a GET operation may have a request body (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/installment
  • The body of a PATCH request is kept as compact as possible, only required and relevant attributes are used.

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. 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

Feedback

Thanks for your feedback.

Post your comment on this topic.

Post Comment