shortname: BEP-7
name: Definition of the BigchainDB Public API
type: Informational
status: Raw
editor: Troy McConaghy <troy@bigchaindb.com>
The "public interface" or "public API" of any software is the stuff that external users or developers see and use to interact with it. These are different from internal APIs, which are used only by the developers developing the internal "black box" code. This BEP summarizes what's included (and not included) in the "BigchainDB Public API." It also explains what it means that BigchainDB follows semantic versioning (and which variety of that).
The definition of the BigchainDB Public API was in the CHANGELOG.md file, which is not the obvious place to look for it.
External users want to be able to guess, based on the version number of a release, what has changed, if anything. To make that possible, BigchainDB Server (and affiliated projects) use the Python form of Semantic Versioning (or at least we try). It's almost the same as regular semantic versioning except release candidates are labelled like 3.4.5rc2 not 3.4.5-rc2 (with no hyphen).
The BigchainDB Server Public API includes:
- The configuration defaults, schemas, and paths where configuration files are stored.
- The Command Line Interface, i.e.
bigchaindb subcommand STUFF - The Transaction Spec.
- The HTTP API (including payloads sent to and received from them, so it includes transactions here again).
- The Events API, also called the Event Stream API.
The BigchainDB Public API excludes:
- Everything marked as "experimental" (even if the feature is part of the Public API).
- The logs generated by the server.
- The internal API, such as classes, methods, functions.
At the time of writing, the various components of the BigchainDB Public API were documented in various places. Those were:
- Configuration settings (latest release)
- Command Line Interface (latest release)
- Transactions Specs (all versions)
- HTTP API (latest release)
- Events API (latest release)
To the extent possible under law, all contributors to this BEP
have waived all copyright and related or neighboring rights to this BEP.