Bigchaindb: [http api] Consolidate the two root URLs into one root

[sbellem]

BigchainDB exposes an HTTP API to allow clients to communicate with its cluster. This HTTP API as two roots:

• /
• /api/v1

The first one simply provides basic information about the node the connection was established with, whereas the second one provides information about the HTTP API itself, and is the basis/root for all endpoitns, such as /transactions.

This ticket proposes to merge these two roots into one, simply because it would make the interaction with BigchainDB simpler.

If, in the future, we do need this distinction/split we can re-introduce it then, but for now, this ticket proposes to keep things simple, as it will save work in multiple areas of the stack.

[sohkai]

Note the resolution of this issue this may impact the ability of a user to query for if a BigchainDB node supports the events API (since that is currently specced to be in the /response).

[ttmc]

I think there is a meaningful semantic difference between a server (at /) and an API (at /api/v1), and therefore I don't favour deleting one of those endpoints.

The Kubernetes deployment of BigchainDB Server currently uses the GET / endpoint for its livenessProbe and readinessProbe, although there is a proposal to create a health endpoint for that instead.

[TimDaub]

@ttmc I listed proposals for this issue here: https://github.com/bigchaindb/bigchaindb/blob/dfac179b0d09e25c51f5d80e3ec6717613ac85db/bdb-ip.md#consolidate--and-apiv1

I'll add another proposal "do nothing".

[krish7919]

@TimDaub @ttmc I wouldn't worry too much about deployment before 1.0. We can change it the way we want to support readiness and/or liveness probes.

[ttmc]

See my comment https://github.com/bigchaindb/bigchaindb/pull/1522/files#r120824533

[r-marques]

The proposal agreed by the team was to keep all the information in the root endpoint so that clients can get all the information from a single http call

• / becomes:

{
    "api": {
        "v1": {
            "docs": "https://docs.bigchaindb.com/projects/server/en/v0.11.0.dev/http-client-server-api.html",
            "statuses": "http://example.com:9984/api/v1/statuses/",
            "streams": "ws://example.com:9985/api/v1/streams/valid_tx",
            "transactions": "http://example.com:9984/api/v1/transactions/",
            "assets": "http://example.com:9984/api/v1/assets/",
            "outputs": "http://example.com:9984/api/v1/outputs/"
        }
    },
    "docs": "https://docs.bigchaindb.com/projects/server/en/v0.11.0.dev/",
    "keyring": [
        "6qHyZew94NMmUTYyHnkZsB8cxJYuRNEiEpXHe1ih9QX3",
        "AdDuyrTyjrDt935YnFu4VBCVDhHtY2Y6rcy7x2TFeiRi"
    ],
    "public_key": "NC8c8rYcAhyKVpx1PCV65CBmyq4YUbLysy3Rqrg8L8mz",
    "software": "BigchainDB",
    "version": "0.11.0.dev"
}

• and /api/v1:

{
    "docs": "https://docs.bigchaindb.com/projects/server/en/v0.11.0.dev/http-client-server-api.html",
    "statuses": "http://example.com:9984/api/v1/statuses/",
    "streams": "ws://example.com:9985/api/v1/streams/valid_tx",
    "transactions": "http://example.com:9984/api/v1/transactions/",
    "assets": "http://example.com:9984/api/v1/assets/",
    "outputs": "http://example.com:9984/api/v1/outputs/"
}

Note that we are also adding the new enpoints for assets and outputs

[TimDaub]

@r-marques FYI: I edited your comment to remove _v1 from streams_v1.