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
|
||||
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
|
||||
`txid` and `tx_id` in data models and HTTP API were renamed to
|
||||
`transaction_id`.
|
||||
`txid`, `tx` and `tx_id` in data models and HTTP API were renamed to
|
||||
`transaction_id` or `transaction`.
|
||||
|
||||
|
||||
### Changes to the Data Model
|
||||
## Breaking Changes to the Data Model
|
||||
|
||||
#### Output amount is now a string
|
||||
|
||||
@ -80,7 +90,7 @@ document.
|
||||
|
||||
#### 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
|
||||
Crypto-Conditions specification. To send transactions to BigchainDB v1.0, all
|
||||
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.
|
||||
|
||||
|
||||
## 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