DataBag API Overview

Introduction

Databag is a decentralized network with the goal of giving people back control of their data. The network supports a wide range of applications including contact apps, photo albums, video players, and social networks. Apps that connect to the Databag network must always be open-source to ensure privacy expectations are met. 

The node comprising the Databag network is designed for self-hosting, allowing a person to host their data and that of their friends and family if they choose. When a person stores their data in a node, they have fine grain control on how it is shared with others. Since a person’s data is stored on a node they control, they can switch from one application to another, and their data goes with them. 

The API primarily focuses on the relationship between data and contacts for access control. Data is stored as abstract objects to be defined by the connecting applications. Each person on the network is identified with a decentralized identifier (DID) so they are not permanently tied to a domain or a hosting provider. If a person migrates their account to another node, the contact relationships remain intact.

Mechanisms

Data is synchronized between apps and the network nodes through the maintenance of a revision tree. Data objects are grouped together, and those groups are grouped together. When one object changes the revision of that object is incremented as well as all the parent nodes of the tree. An app maintaining the same revision tree can identify and update any changed object by updating any node where the revision has changed.

Accounts on the network can be connected for the purposes of sharing data. The connection is formed by exchanging signed messages containing access tokens. Because each account, identified by a DID, is backed by a public/private key, the token exchange can be done securely. All further communication between contacts is done using the exchanged token so the identity can be determined. 

API Objects

The primary data objects in the network are defined by how they are shared while their content is defined by the applications that use them; they consist of articles, topics and tags. Articles are assigned a contact set; contacts can be part of more than one set. Access is granted to the contact when they are part of a set that is assigned to the article. Topics are shared by creating a dialogue, and assigning both contacts and data objects to that dialogue. This difference between articles and topics is subtle; contacts can each have a different view of the set of articles, while members of a dialogue all have the same view of the topics. Finally tags are shared by assigning them to an article or a topic. When a contact has access to an article or topic, they have access to all the assigned tags as well. 

The list of objects used in the API follow:

• profile: a public description of an account, includes options fields such as name and image
• cards: reference to other accounts existing on the network
• apps: applications attached to the account
• articles: content defined by applications 
• topics: content defined by applications 
• tags: content defined by applications 
• groups: bundle contacts together and can be assigned to articles for sharing
• dialogue: bundle topics together and can be assigned to a contact for sharing
• insight: reference to a dialogue on a contacts account
• labels: bundles articles together to form things like an album and can also be shared with a group

API Modules

The API is divided into 9 different modules:

• admin - Used by a system administrator via a browser application to configure and manage the server. Methods for creating new accounts or resetting the password on existing accounts are included.
• account - Used by an account holder via a browser application to manage the account. Methods for attaching an application to the account are included.
• profile - Manages the accounts public profile. A signed message of the public profile can be generated to distribute the profile to new entities.
• share - Supports adding and removing of share groups. 
• content - Allows for adding, updating, sharing, and removing articles from the account. Also allows for organizing the articles by label and assigning those labels or articles to a share group. Articles added to an account need to be processed by stripping any metadata and possibly transcoded before it can be shared. Articles are initially in a not-confirmed and not-ready state. The article is set to confirmed once it has been fully specified, and set to ready when the processing has finished. 
• contact - Manages the set of cards referencing contacts on the network. Also supports assigning cards to a share group. Cards can be in several states:
  • confirmed - a card that has been added to the account but no token exchange has occurred. 
  • requested - the contact has requested a token exchange for connection
  • connecting - the account holder has requested a token exchange for connection
  • connected - a token exchange has occurred and articles, topics, and tags can be shared
  • pending - an unknown contact has requested a token exchange for connection.
• conversation - Supports the creation of dialogues and topics within the dialogue. When a contact is added to the dialogue, a reference to the dialogue can also be added to that contact’s account in the form of an insight. When a dialogue update occurs, the insight is also updated.
• authorization - Generates a signed message to verify the account holder’s identity for some external service. This is primarily used when attaching an app to an account.
• status - Provides a websocket connection to an app for receiving revision updates. When any change occurs, the associated module maintains a revision that is incremented. An app can then reflect changes to the account without polling.