-
Notifications
You must be signed in to change notification settings - Fork 123
API Design
Services maintain types, similar to mime-types, with a 'type/sub-type' format. A Connector may have multiple service types represented, each with a sub-type reflecting that Connector (ie, contact/twitter, link/twitter, message/twitter), and a Collection may have multiple sub-types, with the primary type representing that Collection (ie, contact/twitter, contact/google, contact/facebook).
Basic Connector Architecture Notes
Connectors are supported by data stores that are historical and archival. This means that they include all records as atomic and immutable entries, with 'edits' and 'deletes' being stored as additional entries that reference the target entity in the store, rather than modifying or deleting it in place. Additionally, the data in the store is preserved in a non-compressed and easily accessible format, such that the data will remain accessible via multiple means as technologies evolve over the years.
Records in a collection should always support the following fields on each record:
- Record ID
- Timestamp
- Source
- Reference ID (only if 'edit' or 'delete')
- Document Body
Basic Connector API Methods
Within the flow of the Locker, Connectors will primarily serve Collections as data sources, and the exposed methods reflect that pattern.
-
/getTypes: Returns the list of Service Types currently represented in the Connector. -
/getAll: Retrieve all records, in chronological order. -
/getID: Retrieve a specific record, and any records that reference it. -
/getSince: Retrieve all records since either a Timestamp or ID argument. -
/getCurrent: Retrieve a consolidated set of records with all edits or deletes applied to the set.
Basic Collection Architecture Notes
Collections maintain two data stores - a historical and archival store, similar to Connectors, and a dynamic document store, that provides a more flexible and query-able index of the Collection. The historic document store is the record of the objects that the Collection has composed from other data sources (Connectors or apps), with Reference IDs pointing to source data for each object. The dynamic document store is the primary resource addressed by the data methods of the API.
Basic Collection API Methods
Collections are the primary data resource for apps, and the exposed methods reflect that. GET methods are currently exposed, and POST methods will be updated shortly. GET methods will be provided for all retrieval endpoints, and all edits and deletes will be done via POST endpoints (to more clearly reflect the fact that 'edits' and 'deletes' create records of those types that reference internal records, rather than modifying data in place).