API Documentation

A guide for how to document the data structures and API definitions in the Building Block templates.

Each BB will be responsible for documenting the data structures and APIs that must be implemented by a candidate product. The documentation will be done iteratively, identifying a subset of the BB functionality and creating the specifications for how the functionality will be implemented.

This documentation is not technical, but rather an ‘English’ description of what the APIs do, what data they require and what data they return. From these documents, the more technical OpenAPI specifications can be created.

Data Structures

This section provides information on the core data structures/data models that are used by a Building Block. These data structures describe information that is exchanged between building blocks - they do not dictate internal data structures for a particular implementation. These data structures should also describe the minimum set of information that should be passed in an API call. The data structures can be extended for particular use cases.

These structures should be stored in the Building Block specification document in GitBook (section 7).

For each data model, the following information should be provided:

• Name

• Description

• Fields - the various fields in this data structure. Each field definition should contain the following:

  • Name

  • Type (string, Boolean, number, date, etc)

  • Description

  • Foreign Key (does this field reference another data structure)

  • Constraints (does the field need to be unique, is it the primary key)

  • Required (Y/N)

  • You can also reference any standards that must be adhered to (ie. UTC standard for date/times)

APIs and Endpoints

Once the data structures have been defined, the APIs/endpoints that must be implemented for any compliant product can be described. The APIs should be defined using OpenAPI (Swagger) format and should be stored in the Building Block repository (in the /api directory). They can then be imported to the Service API section of the Building Block specification from the json or yaml file that contains the OpenAPI definition.

Data Structure Example

The following provides an example set of data structures. Note, the BB lead may use a tool like Lucid or Draw.io to develop a data structure diagram:

Open

The data structures can also be defined as follows:

WorkList Data Structure:

Description: The WorkList data structure is used to track a list of subscribers to a particular session or event.

Fields:

Notes: The status field is an enum that is defined with the following fields: ACTIVE, SUSPENDED, CANCELED

API Example

The following provides examples of API definitions. The OpenAPI definition can be extracted from these English definitions:

Endpoint: /alert

Endpoint: /alert/{id}