API design guidelines

Each Vital customer is represented as an Org.
Vital API comprises of multiple regional environments (US, EU, etc)
Within each Vital API regional environment, an Org can have one or more groups of Users, represented as Teams.

Vital API is the SaaS application plane:

✅ It provides user management and order management capabilities for each Team.
✅ It provides access to all structured data associated with Users and Orders.
✅ It is responsible for ingesting new data, both via regular polling and receiving pushed data from providers and labs.
❌ It cannot be used to inspect or change any settings of the Teams or the Orgs.

Org Management API is the SaaS control plane:

✅ It provides administrative capability for the Orgs themselves, such as Billing and (Admin) Memberships.
✅ It provides the means to create and delete Teams, as well as
✅ It manages all aspects of Team configurations and settings.
❌ It cannot be used to access users, orders, and associated data of any specific Team.

Case studies:

Considering the requirement for programmatically customizing Brand Information:
- Brand Information is a team configuration.
- Therefore, it should be exposed through the Org Management API.
Considering the requirement to expose Body Temperature data:
- Body Temperature data are associated data of a User in a Team.
- Therefore, it should be exposed through the Vital API.

Field naming

General

Prefer full name over abbreviation. Use abbreviation sparingly, and only when it is an established, unambiguous terms of art.
- ✅ HRV instead of heart rate variability
- ✅ API instead of application programming interface
- ❌ HR instead of heart rate
- ❌ DoB instead of date of birth

Standard fields

Pagination

General

Prefer cursor-based pagination whenever possible. For example:

The dataset only needs to be forward paginated.
The endpoint provides a comprehensive filtering and sorting options.

Use offset-based pagination only when the use case strictly requires:

bidirectional pagination; and
the ability to jump between pages.

… which is rarely observed in practice.

It is always preferrable to provide more filtering options — so that the result set can be narrowed down — over providing precise offset-based pagination to walk over the whole dataset.

Cursor-based pagination (Recommended)

Query parameter:

next_cursor (optional): The cursor for fetching the next page.

Response field:

The top-level item array (of the current page) should be named after the entity in plural form.
The cursor for the next page must be provided at $.next_cursor. If there is no more data, $.next_cursor must be null.

Copy

GET /v2/data?next_cursor=bm90IGlwc3VtIGxvcmVuIGlwc3Vt

{
  "credentials": [
    { ... },
    { ... },
  ],
  "next_cursor": "bG9yZW0gaXBzdW0gbG9yZW0gaXBzdW0="
}

Offset-based pagination

Query parameters:

page (optional): The page index to fetch; one-based.
size (optional): The page size to use.

Response field: