Skip to content

Latest commit

 

History

History
55 lines (40 loc) · 2.96 KB

README.md

File metadata and controls

55 lines (40 loc) · 2.96 KB
Raw
shortname: BEP-7
name: Definition of the BigchainDB Public API
type: Informational
status: Raw
editor: Troy McConaghy <troy@bigchaindb.com>

Abstract

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).

Motivation

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).

Specification

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.

Documentation of the Current BigchainDB Public API

At the time of writing, the various components of the BigchainDB Public API were documented in various places. Those were:

Copyright Waiver

CC0
To the extent possible under law, all contributors to this BEP have waived all copyright and related or neighboring rights to this BEP.