Mirroristas/bigchaindb
2
0
Fork 0
mirror of https://github.com/bigchaindb/bigchaindb.git synced 2024-10-13 13:34:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Minor edits & fixes to WebSocket API docs

Browse Source
This commit is contained in:
Troy McConaghy 2017-05-04 15:04:54 +02:00
parent 07a9e69933
commit 8297ce9260
1 changed files with 21 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
docs/server/source/websocket-event-stream-api.rst
View File

@ -8,9 +8,8 @@ The WebSocket Event Stream API
BigchainDB provides real-time event streams over the WebSocket protocol with BigchainDB provides real-time event streams over the WebSocket protocol with
the Event Stream API. the Event Stream API.
Connecting to an event stream from your application enables a BigchainDB node Connecting to an event stream from your application enables a BigchainDB node
to notify you as events are processed, such as new `validated transactions <#valid-transactions>`_. to notify you as events occur, such as new `validated transactions <#valid-transactions>`_.
Demoing the API Demoing the API
@ -23,25 +22,31 @@ to familiarize yourself before attempting an integration.
Determining Support for the Event Stream API Determining Support for the Event Stream API
-------------------------------------------- --------------------------------------------
In practice, it's a good idea to make sure that the node you're connecting with It's a good idea to make sure that the node you're connecting with
has advertised support for the Event Stream API. To do so, send a HTTP GET has advertised support for the Event Stream API. To do so, send a HTTP GET
request to the node's :ref:`Root URL <bigchaindb-root-url>` and check that the request to the node's :ref:`API Root Endpoint`
response contains a ``streams_<version>`` property in ``_links``:: (e.g. ``http://localhost:9984/api/v1/``) and check that the
response contains a ``streams_<version>`` property in ``_links``:
.. code:: JSON
{ {
"_links": { "_links": {
"streams_v1": "ws://example.com:9985/api/v1/streams/" ...,
"streams_v1": "ws://example.com:9985/api/v1/streams/valid_tx",
...
} }
} }
Connection Keep Alive Connection Keep-Alive
~~~~~~~~~~~~~~~~~~~~~ ---------------------
The Event Stream API initially does not provide any mechanisms for connection The Event Stream API initially does not provide any mechanisms for connection
keep alive other than enabling TCP keepalive on each open WebSocket connection. keep-alive other than enabling TCP keepalive on each open WebSocket connection.
In the future, we may add additional functionality to handle ping/pong frames In the future, we may add additional functionality to handle ping/pong frames
or payloads designed for keep alive. or payloads designed for keep-alive.
Streams Streams
------- -------
@ -54,8 +59,8 @@ Streams will always be under the WebSocket protocol (so ``ws://`` or
``wss://``) and accessible as extensions to the ``/api/v<version>/streams/`` ``wss://``) and accessible as extensions to the ``/api/v<version>/streams/``
API root URL (for example, `validated transactions <#valid-transactions>`_ API root URL (for example, `validated transactions <#valid-transactions>`_
would be accessible under ``/api/v1/streams/valid_tx``). If you're running your would be accessible under ``/api/v1/streams/valid_tx``). If you're running your
own BigchainDB instance and need help determining its root URL, you can find own BigchainDB instance and need help determining its root URL,
more :ref:`here <determining-the-api-root-url>`. then see the page titled :ref:`Determining the API Root URL`.
All messages sent in a stream are in the JSON format. All messages sent in a stream are in the JSON format.
@ -68,7 +73,7 @@ All messages sent in a stream are in the JSON format.
as a specific ``output``'s ``public_key``. as a specific ``output``'s ``public_key``.
If you have specific use cases that you think would fit as part of this If you have specific use cases that you think would fit as part of this
API, feel free to reach out via `gitter <https://gitter.im/bigchaindb/bigchaindb>`_ API, feel free to reach out via `Gitter <https://gitter.im/bigchaindb/bigchaindb>`_
or `email <mailto:product@bigchaindb.com>`_. or `email <mailto:product@bigchaindb.com>`_.
Valid Transactions Valid Transactions
@ -79,7 +84,9 @@ Valid Transactions
Streams an event for any newly validated transactions. Message bodies contain Streams an event for any newly validated transactions. Message bodies contain
the transaction's ID, associated asset ID, and containing block's ID. the transaction's ID, associated asset ID, and containing block's ID.
Example message:: Example message:
.. code:: JSON
{ {
"tx_id": "<sha3-256 hash>", "tx_id": "<sha3-256 hash>",