mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
First cut HTTP API and WebSocket API changes
This commit is contained in:
tim
parent
9cb6904c4e
commit
ac6183475b
@ -26,16 +26,26 @@ you to upgrade efficiently.
|
|||||||
The next sections will go over each of the above mentioned interfaces and
|
The next sections will go over each of the above mentioned interfaces and
|
||||||
detail the exact changes.
|
detail the exact changes.
|
||||||
|
|
||||||
### Syntactical changes
|
## A note upfront
|
||||||
|
|
||||||
#### `txid` and `tx_id` becomes `transaction_id`
|
We tried to test this upgrade guide as best as we could by using it to adjust
|
||||||
|
our official drivers. If you still find breaking changes that causes your
|
||||||
|
software to crash, please let us and others reading this guide know by sending
|
||||||
|
over a Pull-Request or notifying us on Gitter.
|
||||||
|
|
||||||
|
Thank you very much :)
|
||||||
|
|
||||||
|
|
||||||
|
## Syntactical changes
|
||||||
|
|
||||||
|
#### `tx`, `txid` and `tx_id` becomes `transaction_id`
|
||||||
|
|
||||||
To establish better consistency between external interfaces, all usages of
|
To establish better consistency between external interfaces, all usages of
|
||||||
`txid` and `tx_id` in data models and HTTP API were renamed to
|
`txid`, `tx` and `tx_id` in data models and HTTP API were renamed to
|
||||||
`transaction_id`.
|
`transaction_id` or `transaction`.
|
||||||
|
|
||||||
|
|
||||||
### Changes to the Data Model
|
## Breaking Changes to the Data Model
|
||||||
|
|
||||||
#### Output amount is now a string
|
#### Output amount is now a string
|
||||||
|
|
||||||
@ -80,7 +90,7 @@ document.
|
|||||||
|
|
||||||
#### Update to Cryptoconditions version 2
|
#### Update to Cryptoconditions version 2
|
||||||
|
|
||||||
Earlier the IETF Interledger working group released an [updated
|
Earlier this year the IETF Interledger working group released an [updated
|
||||||
draft](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02) of their
|
draft](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02) of their
|
||||||
Crypto-Conditions specification. To send transactions to BigchainDB v1.0, all
|
Crypto-Conditions specification. To send transactions to BigchainDB v1.0, all
|
||||||
transaction's inputs and outputs need to comply to this new version.
|
transaction's inputs and outputs need to comply to this new version.
|
||||||
@ -97,3 +107,290 @@ If you don't find your preferred language in this list, do not despair but
|
|||||||
reach out to us for help on Github/Gitter or product@bigchaindb.com.
|
reach out to us for help on Github/Gitter or product@bigchaindb.com.
|
||||||
|
|
||||||
|
|
||||||
|
## Breaking Changes to the HTTP API
|
||||||
|
|
||||||
|
In this section, we'll go over each of the endpoints separately and list the
|
||||||
|
changes done to them:
|
||||||
|
|
||||||
|
|
||||||
|
### `GET /`
|
||||||
|
|
||||||
|
Documentation:
|
||||||
|
|
||||||
|
- [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#bigchaindb-root-url)
|
||||||
|
- [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#bigchaindb-root-url)
|
||||||
|
|
||||||
|
|
||||||
|
Changes:
|
||||||
|
|
||||||
|
- All notion of `_links` was removed
|
||||||
|
- `api_v1` is now an object including currently only one further object called
|
||||||
|
`v1`
|
||||||
|
- `api.v1` includes links that were originally only available through
|
||||||
|
`/api/v1/`
|
||||||
|
- `api.v1` now also includes links to `assets` (a new endpoint) and `outputs`
|
||||||
|
- `streams_v1`'s link was changed from `streams/valid_tx` to
|
||||||
|
`streams/valid_transactions`
|
||||||
|
- `streams_v1` was renamed to `streams`
|
||||||
|
- Usages of scheme, host and port to API V1's endpoints were removed to allow
|
||||||
|
for configurations of BigchainDB behind reverse proxies
|
||||||
|
- e.g. `http://example.com:9984/api/v1/transactions` ==>
|
||||||
|
`/api/v1/transactions`
|
||||||
|
|
||||||
|
|
||||||
|
```json
|
||||||
|
// Old
|
||||||
|
{
|
||||||
|
"_links": {
|
||||||
|
"api_v1": "http://example.com:9984/api/v1/",
|
||||||
|
"docs": "https://docs.bigchaindb.com/projects/server/en/v0.10.2/"
|
||||||
|
},
|
||||||
|
"keyring": [
|
||||||
|
"6qHyZew94NMmUTYyHnkZsB8cxJYuRNEiEpXHe1ih9QX3",
|
||||||
|
"AdDuyrTyjrDt935YnFu4VBCVDhHtY2Y6rcy7x2TFeiRi"
|
||||||
|
],
|
||||||
|
"public_key": "NC8c8rYcAhyKVpx1PCV65CBmyq4YUbLysy3Rqrg8L8mz",
|
||||||
|
"software": "BigchainDB",
|
||||||
|
"version": "0.10.2"
|
||||||
|
}
|
||||||
|
|
||||||
|
// New
|
||||||
|
{
|
||||||
|
"api": {
|
||||||
|
"v1": {
|
||||||
|
"docs": "https://docs.bigchaindb.com/projects/server/en/v0.11.0.dev/http-client-server-api.html",
|
||||||
|
"statuses": "/api/v1/statuses/",
|
||||||
|
"streams": "ws://example.com:9985/api/v1/streams/valid_transactions",
|
||||||
|
"transactions": "/api/v1/transactions/",
|
||||||
|
"assets": "/api/v1/assets/",
|
||||||
|
"outputs": "/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"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `GET /api/v1`
|
||||||
|
|
||||||
|
Documentation:
|
||||||
|
|
||||||
|
- [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#api-root-endpoint)
|
||||||
|
- [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#api-root-endpoint)
|
||||||
|
|
||||||
|
Changes:
|
||||||
|
|
||||||
|
- All notion of `_links` was removed
|
||||||
|
- The response object of `/api/v1` now includes links to `assets` (a new
|
||||||
|
endpoint) and `outputs`
|
||||||
|
- `streams_v1`'s link was changed from `streams/valid_tx` to
|
||||||
|
`streams/valid_transactions`
|
||||||
|
- `streams_v1` was renamed to `streams`
|
||||||
|
- Usages of scheme, host and port to API V1's endpoints were removed to allow
|
||||||
|
for configurations of BigchainDB behind reverse proxies
|
||||||
|
- e.g. `http://example.com:9984/api/v1/transactions` ==>
|
||||||
|
`/api/v1/transactions`
|
||||||
|
|
||||||
|
|
||||||
|
```json
|
||||||
|
// Old
|
||||||
|
{
|
||||||
|
"_links": {
|
||||||
|
"docs": "https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html",
|
||||||
|
"self": "http://example.com:9984/api/v1/",
|
||||||
|
"statuses": "http://example.com:9984/api/v1/statuses/",
|
||||||
|
"streams_v1": "ws://example.com:9985/api/v1/streams/valid_tx",
|
||||||
|
"transactions": "http://example.com:9984/api/v1/transactions/"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// New
|
||||||
|
{
|
||||||
|
"docs": "https://docs.bigchaindb.com/projects/server/en/v0.11.0.dev/http-client-server-api.html",
|
||||||
|
"statuses": "/api/v1/statuses/",
|
||||||
|
"streams": "ws://example.com:9985/api/v1/streams/valid_transactions",
|
||||||
|
"transactions": "/api/v1/transactions/",
|
||||||
|
"assets": "/api/v1/assets/",
|
||||||
|
"outputs": "/api/v1/outputs/"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
### `GET /api/v1/transactions/{tx_id}`
|
||||||
|
|
||||||
|
Documentation:
|
||||||
|
|
||||||
|
- [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#get--api-v1-transactions-tx_id)
|
||||||
|
- [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#get--api-v1-transactions-transaction_id)
|
||||||
|
|
||||||
|
|
||||||
|
Changes:
|
||||||
|
|
||||||
|
- Previously this endpoint returned transactions from BigchainDB's `BACKLOG`
|
||||||
|
and from blocks marked as `UNDECIDED`. With version 1.0, this endpoint will
|
||||||
|
only return transactions included in blocks marked as `VALID`.
|
||||||
|
|
||||||
|
|
||||||
|
### `POST /api/v1/transactions`
|
||||||
|
|
||||||
|
Documentation:
|
||||||
|
|
||||||
|
- [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#post--api-v1-transactions)
|
||||||
|
- [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#post--api-v1-transactions)
|
||||||
|
|
||||||
|
|
||||||
|
Changes:
|
||||||
|
|
||||||
|
- A `Location` HTTP header was included in the endpoint's response to allow
|
||||||
|
users to check the transaction's status more easily via the
|
||||||
|
`/statuses?transaction_id` endpoint
|
||||||
|
|
||||||
|
|
||||||
|
### `GET /api/v1/outputs`
|
||||||
|
|
||||||
|
Documentation:
|
||||||
|
|
||||||
|
- [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#get--api-v1-outputs?public_key=public_key)
|
||||||
|
- [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#get--api-v1-outputs?public_key=public_key)
|
||||||
|
|
||||||
|
|
||||||
|
Changes:
|
||||||
|
|
||||||
|
- Reversed the behavior of the `unspent` query parameter to `spent`, implying
|
||||||
|
the following behavior:
|
||||||
|
- If `?spent=true`, the response is an array of all spent outputs
|
||||||
|
associated with a given public key
|
||||||
|
- If `?spent=false`, response is an array of all NOT YET spent (or
|
||||||
|
"unspent" outputs associated with a given public key
|
||||||
|
- If no ``spent=` filter is present in the request, the response is an
|
||||||
|
array of all outputs associated with a given public key (spent and
|
||||||
|
unspent)
|
||||||
|
|
||||||
|
Previously the response included a list of relative URLs pointed to
|
||||||
|
transations' outputs:
|
||||||
|
|
||||||
|
```json
|
||||||
|
// Old
|
||||||
|
[
|
||||||
|
"../transactions/2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e/outputs/0"
|
||||||
|
]
|
||||||
|
|
||||||
|
// New
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"output": 0,
|
||||||
|
"transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
In the future, we're planning to [upgrade this endpoint
|
||||||
|
further](https://github.com/bigchaindb/bigchaindb/blob/99499b1f8783719a082813912ac9a0d363ae278f/bdb-ip.md#6-a-new-outputs-endpoint)
|
||||||
|
to meet the requirements of [our
|
||||||
|
users](https://github.com/bigchaindb/bigchaindb/issues/1227#issuecomment-307297473).
|
||||||
|
|
||||||
|
|
||||||
|
### `GET /api/v1/statuses?tx_id`
|
||||||
|
|
||||||
|
Documentation:
|
||||||
|
|
||||||
|
- [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#get--api-v1-statuses?tx_id=tx_id)
|
||||||
|
- [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#get--api-v1-statuses?transaction_id=transaction_id)
|
||||||
|
|
||||||
|
|
||||||
|
Changes:
|
||||||
|
|
||||||
|
- All notion of `_links` was removed. In case of querying the status of a
|
||||||
|
transaction already included in a block marked `VALID`, no `_links` object is
|
||||||
|
provided anymore. The response object now only contains a single key value
|
||||||
|
pair named `status`
|
||||||
|
- The query parameter `tx_id` was renamed to `transaction_id`, e.g. `GET
|
||||||
|
/api/v1/statuses?transaction_id=`
|
||||||
|
|
||||||
|
|
||||||
|
```json
|
||||||
|
// Old
|
||||||
|
{
|
||||||
|
"status": "valid",
|
||||||
|
"_links": {
|
||||||
|
"tx": "/transactions/04c00267af82c161b4bf2ad4a47d1ddbfeb47eef1a14b8d51f37d6ee00ea5cdd"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// New
|
||||||
|
{
|
||||||
|
"status": "valid",
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
### `GET /api/v1/statuses?block_id`
|
||||||
|
|
||||||
|
Documentation:
|
||||||
|
|
||||||
|
- [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#get--api-v1-statuses?block_id=block_id)
|
||||||
|
- [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#get--api-v1-statuses?block_id=block_id)
|
||||||
|
|
||||||
|
|
||||||
|
Changes:
|
||||||
|
|
||||||
|
- All notion of `_links` was removed. The response object now only contains a
|
||||||
|
single key value pair named `status`
|
||||||
|
|
||||||
|
|
||||||
|
```json
|
||||||
|
// Old
|
||||||
|
{
|
||||||
|
"status": "valid",
|
||||||
|
"_links": {
|
||||||
|
"tx": "/transactions/04c00267af82c161b4bf2ad4a47d1ddbfeb47eef1a14b8d51f37d6ee00ea5cdd"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// New
|
||||||
|
{
|
||||||
|
"status": "valid",
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
### `GET /api/v1/blocks?tx_id`
|
||||||
|
|
||||||
|
Documentation:
|
||||||
|
|
||||||
|
- [Old](https://docs.bigchaindb.com/projects/server/en/v0.10.2/http-client-server-api.html#get--api-v1-blocks?tx_id=tx_id&status=UNDECIDED|VALID|INVALID)
|
||||||
|
- [New](https://docs.bigchaindb.com/projects/server/en/v1.0.0/http-client-server-api.html#get--api-v1-blocks?transaction_id=transaction_id&status=UNDECIDED|VALID|INVALID)
|
||||||
|
|
||||||
|
|
||||||
|
Changes:
|
||||||
|
|
||||||
|
- The query parameter `tx_id` was renamed to `transaction_id`, e.g. `GET
|
||||||
|
/api/v1/blocks?transaction_id`
|
||||||
|
|
||||||
|
|
||||||
|
## Breaking Changes to the WebSocket Event Stream API
|
||||||
|
|
||||||
|
In the event object sent to a listener, `tx_id` was renamed to
|
||||||
|
`transaction_id`.
|
||||||
|
|
||||||
|
```json
|
||||||
|
// Old
|
||||||
|
{
|
||||||
|
"tx_id": "<sha3-256 hash>",
|
||||||
|
"asset_id": "<sha3-256 hash>",
|
||||||
|
"block_id": "<sha3-256 hash>"
|
||||||
|
}
|
||||||
|
|
||||||
|
// New
|
||||||
|
{
|
||||||
|
"transaction_id": "<sha3-256 hash>",
|
||||||
|
"asset_id": "<sha3-256 hash>",
|
||||||
|
"block_id": "<sha3-256 hash>"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user