BFD API¶
Interactions with the Big Friendly Datastore are via a REST-ful API described below.
The five core concepts needed to understand the API are:
Users - real humans who interact with the BFD. Admin users are able to create new users. All users interact with the BFD via the API and use either token-based HTTP authentication via an HTTP
Authorizationheader in all requests, or via session management if interacting with the BFD via its browser based frontend.Namespaces - define who is annotating data. Namespaces have a unique name and a free text description to provide context. Users are automatically given a namespace with the same name as their username. Further namespaces may be created to represent organisational units. Namespaces must have at least one user, and potentially many users, to act as administrators. They define the tags and the permissions relating to tags that belong to the Namespace.
Tags - define what is annotated to objects. Tags belong to a parent namespace, so it’s possible to understand who is annotating what within the BFD. Tags have a name that is unique within the parent namespace and a free text description to provide context. Tags can be either public (anyone can read values associated with them) or private (only whitelisted individuals can read values annotated with them). Furthermore, only namespace admins or those users listed in a “users” whitelist are able to use the tag to annotate values onto an object. Finally, tags are typed so if a tag is for storing a date-time value, an operation to use it to annotate a string value will fail.
Objects - represent things in the universe. Objects are identified by a unique name. What an object represents can be found out by looking at the aggregation of values annotated to the object via BFD’s user’s namespaces and tags.
Values - are the data associated with an object via a namespace/tag combination. Values can be used with the query language to find objects of interest.
Users¶
GET /u/<username>
Returns limited information about the user identified by username. Admin
users and the user identified by username see a more comprehensive profile.
POST /u/<username>
Use JSON data to update the referenced user. Only works if the request is made
by an admin user of the user identified by username.
POST /u/new
Creates a new user from the JSON data provided by an admin user.
Namespaces¶
GET /n/<namespace>
Returns the description associated with the referenced namespace.
PUT /n/<namespace>
Use JSON data to update the referenced namespace. Only works if the request
is made by a global admin user or a user listed as the referenced namespace’s
admin.
POST /n/new
Creates a new namespace from the JSON data provided by an admin user.
