Intro to our API design

In order to get the most functionality out of our API, it is important to understand what each entity's role can be.

Lets take a look at a simplified relational diagram:

User

What stands out quickly is how every entity is connected to a User entity. The user is considered to be the owner of a certain object, and is used to identify which other users can access certain data. For example, a certain role can provide a user access to the objects of other users with mutual groups.

The user is assigned his role upon making an http request to the server. If the user did not exist in this system, the first request will also create a new user record. Only after a user has been added to the system, other users can assign entities to that user. To get all the users you can potentially assign objects to, you can call the users API.

Case

The entities in green are the entities that are used for business record keeping. These are also modifiable through the API. A Case is considered to be a collection of data related to each other. It connects data and provides one endpoint to query all related data.

Proprietor

The Proprietor entity exists to hold data about people that are the owner or beneficiary of a business case. There is an optional relation to other proprietors when requiring a guardian. A relation with a Case is optional too.

Policy

A dedicated entity for insurance related policy data. A relation with a Case is optional.

Document

Meta-data about a document that is uploaded to the system, used to retrieve the original document. To upload a Document, we use another module with a reference to our Case.

Verification

The "Case Keeper Core" API integrates a sub module "KYC Core". That is the module responsible for retrieving subject data and verifying the data. This data is stored in the central Verification entity. Whenever a Verification is updated, an event will be sent to other modules to synchronize their implementation. In "Case Keeper Core", the record is then cached within the database in order to query efficiently in relation to other objects within the system.

Through the API, we can create new verifications and connect them to proprietors.

The relation between verifications and proprietors is many-to-many, therefore we have an extra entity proprietorVerification that holds the relation. It is possible to query specifically based on this relation through the /proprietor-verifications route.

Event

Every time an object is created, updated or deleted, a webhook event will be sent to an upstream server. We provide an API to retrieve missed events, which can also be used as a change log. The Event is an entity which is created on each change and contains the new state of the object's data. The Event will also keep track of the user that updated such data. It is an immutable object.

Events have a key which will contain the entity type and action that triggered the event. The event also contains the response status code from sending the webhook request.