-
Notifications
You must be signed in to change notification settings - Fork 21
API Roadmap
This page is used to define and collaborate on strategic improvements to be made to the API. Initially this is focused on v2.0.0 but will evolve to describe the order and scope of incremental enhancements to get to v2.0.0 and beyond.
All APIs are prototyped on the epic/api-2.0.0 branch.
API resources will be as follows:
-
/health: Health API for the application -
/security: User authentication (token generation, etc.) -
/roles: Defines privilege sets within the application -
/users: Manages users -
/role-grants: Controls which users have what privileges -
/entity-types: Manages entity classification -
/entities: Manages entities (facilities of some sort) -
/contacts: Manages contacts -
/contact-association-types: Manages association classification -
/contact-associations: Manages associations between a contact and one or more entities -
/email: Manages e-mail functionality ("blast" e-mail, password reset, etc.) -
/email-templates: Manages e-mail templates -
/events: Manages event definitions -
/questionnaires: Manages questionnaires (add/remove questions, support versioning) -
/check-ins: Allows a contact to "check in" with some level of additional data
The health API will be implemented to match the prototyped API. Additional checks can be added over time as needed.
NOTE: To minimize maintenance, we may want to look into a framework such as @financial-times/health-check or endoscope.
The /security endpoints are used to obtain a JSON web token (JWT). The token may have the roles associated with the authentication; currently, a valid JWT is sufficient.
The authentication model will need to include verification of the authenticated "user" (either a system user or a contact).
We may need to update the JWT content to omit role information, as roles can be revoked while the JWT is still valid; we should also review the overall JWT content to see what we want to add to the structure and such - there may be a way to handle the non-user access for checkins and such.
JWTs can be generated for system users and by e-mail address (for contacts). The roles granted
Roles are defined as one or more permissions for the application APIs. Each permission specifies an endpoint and one or more HTTP methods for that endpoint (Note: Need to have a concrete way to map endpoints with path parameters - maybe regex?).
Roles are intended to be fine-grained, and limited to specific areas (read user information, administer users, etc.). If possible, we should limit the number of roles using an aggregation-like mechanism, where having the role that allows user administration automatically grants the roles related to read-only user endpoints. This minimizes duplication and allows roles to be more dynamic.
The /roles endpoint allows the retrieval, creation, modification and deletion of roles, and the addition and removal of permissions from roles.
Users are those API consumers who have their own authentication credentials to the application. They explicitly authenticate, and only have access to the APIs that they are granted. Users are not contacts, and are not associated with entities.
The /users endpoint allows retrieval, creation, modification and deletion of users.
Any user can have one or more roles granted to them. Those roles allow an authenticated user to access the APIs using the role-specified HTTP methods.
The /role-grants endpoint allows the granting of roles to and the revocation of roles from a user or contact.
Entity types are ad hoc classifications for entities, such as "assisted living" and "long-term care". Types cannot be changed, and cannot be deleted if in use. Entity types can be used to filter the recipient list for outbound e-mail notifications. Entity types may need to support soft deletion for reporting purposes. This may also change behavior to allow re-creation.
The /entity-types endpoint allows allows retrieval, creation, modification and deletion of entity types.
An entity represents a real-world location that can be associated with a contact, and which can have check-ins completed. Entities can be used to create the recipient list for outbound e-mail notifications. Entities may need to support soft deletion for reporting purposes. This may also change behavior to allow re-creation.
The /entities endpoint allows allows retrieval, creation, modification and deletion of entities.
Contacts represent real-world people that are the point of contact for one or more entities. Contacts can have different responsibilities (contact association types) for different entities. Contacts can be used to create the recipient list for outbound e-mail notifications. Contacts may need to support soft deletion for reporting purposes. This may also change behavior to allow re-creation.
Contact association types are ad hoc classifications for contact associations, such as such as "administrator" and "primary support". Types cannot be changed, and cannot be deleted if in use. Contact association types can be used to filter the recipient list for outbound e-mail notifications. Association types may need to support soft deletion for reporting purposes. This may also change behavior to allow re-creation.
The /contact-association-types endpoint allows allows retrieval, creation, modification and deletion of entity types.
A contact association is a relationship between a contact and an entity. This is a many-to-many relationship, as entities can have multiple contacts, and contacts can be associated with multiple entities. Associations may need to support soft deletion for reporting purposes. This may also change behavior to allow re-creation.
The /contact-associations endpoint allows the creation or removal of entity associations for contact.
From an implementation perspective, we should look at the transporters for nodemailer
The /email endpoint allows transmission of e-mail messages for various use cases. The APIs allow selection of the recipients, and will use internally-rendered templates for the message content. Depending on the API, the template may be specific to the invocation, or hard-coded for the use case.
With a more generic system, the ability to create and modify templates is required. Given that the server side uses Nunjucks, the API must be implemented to prevent the injection of potentially insecure content into the templates. We should also look at other templating engines like Handlebars or Mustache.
We may need to switch to something like using Markdown for the the templates. We can use Marked as a parser, and render the template into HTML or plain text prior to using the templating engine for substitution. We'd probably still want to use something like DOMPurify for the generated HTML. To save on the performance hit, we can render the Markdown on template creation/modification, and store the render results. Then all that we need to do at "blast" time is to perform the templating/substitution.
Non-Markdown content (like JavaScript or HTML inclusion) must be prohibited.
For variable substitution, we should adopt a JSON-style notation for the substituted fields.
The /email-templates endpoint allows creation, retrieval, modification, and removal of e-mail templates.
Events represent a classification of interactions with the check-in system. Check-ins can be associated with events for classification purposes. Events may need to support soft deletion for reporting purposes. This may also change behavior to allow re-creation.
The /events endpoint allows creation, retrieval, modification, and removal of event information.
Questionnaires are intended to define a set of render-capable question definitions that can be displayed to an end user. Questionnaires may need to support soft deletion for reporting purposes. Modifications should also allow versioning and visibility control of versions.
Questions body text can be up to 1024 characters in length. Answers can be of one of the following forms:
- Short text: Free-form text up to 80 characters (should be rendered as a single text input)
- Long text: Free-form text from 80 to 1024 characters (should be rendered as multi-line text input)
- Checkbox List: Provides multiple fixed options; multiple options may be selected
- Option List: Provides multiple fixed options; only a single option may be selected
All question types can be flagged as "required"; the flag defaults to false.
Checkbox and option lists also support a flag to enable an "Other" choice; the flag defaults to false. If a question enables this flag, rendering will include an additional "Other" option. If the user chooses that option, an additional short-text field will be enabled for text input that will be included in the answer.
The /questionnaires endpoint allows creation, retrieval, modification, and removal of questionnaire information.
A check-in is the process of a contact indicating that they have acknowledged the state of their associated entity. Check-ins may be associated with events or questionnaires. Check-ins are always in the context of a contact association.
The /check-ins endpoint allows creation and retrieval of check-in information. Reporting may be a separate API as well.
Need to add REST validation (for example, using express-openapi-validate; see this article for more details)
Add an API that tracks metrics such as:
- Total requests
- Average response times
- Breakdown by resource/path
- Memory & performance characteristics
This is something that would probably be best as a third-party tool we include, rather than writing it from scratch.
A questionnaire is one or more questions (with the potential for multiple-choice or open-ended answers) that can be completed by a contact on behalf of an entity. A questionnaire is usually associated with a check-in.
An event is a way of grouping check-ins and questionnaire responses for a particular set of circumstances (natural disaster, disease outbreak, etc.).
TBD: How are questionnaires associated with events?
An entity can report their status at any point in time. This status is usually associated with additional information, such as that obtained via questionnaire.
TBD: How are questionnaires associated with check-ins?
There is a potential need for a revision history for the following resources:
- Contacts
- Users
- Events
- Entities
- Questionnaires
- Roles
- Role Grants
Revision history will tentatively include:
- Modifying user
- Modification timestamp
- Modification status (created, deleted, modified)
- Modified fields (only for modifications; contains field name, original value and modified value)
The schema and content needs to be determined for the various types of CSV extracts. There should also be some sort of restriction mechanism to prevent all data being exported by unauthorized users (data leaks).
As the intent is to create a more generic CMS, we should evaluate how much internationalization / localization we want to support. Potential areas of impact include:
- Application messages
- Input filtering/validation
- Database design/implementation (field layout, collation, etc.)