mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
115 lines
4.0 KiB
ReStructuredText
115 lines
4.0 KiB
ReStructuredText
The WebSocket Event Stream API
|
|
==============================
|
|
|
|
.. important::
|
|
This is currently scheduled to be implemented in BigchainDB Server 0.10.
|
|
|
|
BigchainDB provides real-time event streams over the WebSocket protocol with
|
|
the Event Stream API.
|
|
|
|
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>`_.
|
|
|
|
|
|
Demoing the API
|
|
---------------
|
|
|
|
You may be interested in demoing the Event Stream API with the `WebSocket echo test <http://websocket.org/echo.html>`_
|
|
to familiarize yourself before attempting an integration.
|
|
|
|
|
|
Determining Support for the Event Stream API
|
|
--------------------------------------------
|
|
|
|
In practice, 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
|
|
request to the node's :ref:`Root URL <bigchaindb-root-url>` and check that the
|
|
response contains a ``streams_<version>`` property in ``_links``::
|
|
|
|
{
|
|
"_links": {
|
|
"streams_v1": "ws://example.com:9984/api/v1/streams/"
|
|
}
|
|
}
|
|
|
|
|
|
Connection Keep Alive
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The Event Stream API requires clients to signal that they'd like their
|
|
connection to stay open by sending "pings" across the open connection.
|
|
BigchainDB nodes will automatically close any connections that haven't sent a
|
|
ping in the last three minutes.
|
|
|
|
.. note::
|
|
|
|
While three minutes is the limit before a BigchainDB server will terminate
|
|
a connection, we suggest sending a ping every 30 seconds for better
|
|
reliability.
|
|
|
|
A "ping" consists of a message containing only the string ``"ping"``, for example
|
|
in JavaScript:
|
|
|
|
.. code-block:: javascript
|
|
|
|
new WebSocket("...").send("ping")
|
|
|
|
If the BigchainDB node received the ping, it'll respond back with a message
|
|
containing only the string ``"pong"``.
|
|
|
|
|
|
Streams
|
|
-------
|
|
|
|
Each stream is meant as a unidirectional communication channel, where the
|
|
BigchainDB node is the only party sending messages (except for `keep-alive
|
|
pings <#connection-keep-alive>`_). Any messages sent to the BigchainDB node
|
|
(except the keep-alive pings) will be ignored.
|
|
|
|
Streams will always be under the WebSocket protocol (so ``ws://`` or
|
|
``wss://``) and accessible as extensions to the ``/api/v<version>/streams/``
|
|
API root URL (for example, `validated transactions <#valid-transactions>`_
|
|
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
|
|
more :ref:`here <determining-the-api-root-url>`.
|
|
|
|
All messages sent in a stream are in the JSON format.
|
|
|
|
.. note::
|
|
|
|
For simplicity, BigchainDB initially only provides a stream for all
|
|
validated transactions. In the future, we may provide streams for other
|
|
information, such as new blocks, new votes, or invalid transactions. We may
|
|
also provide the ability to filter the stream for specific qualities, such
|
|
as a specific ``output``'s ``public_key``.
|
|
|
|
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>`_
|
|
or `email <mailto:product@bigchaindb.com>`_.
|
|
|
|
Valid Transactions
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
``/valid_tx``
|
|
|
|
Streams an event for any newly validated transactions. Message bodies contain
|
|
the transaction's ID, associated asset ID, and containing block's ID.
|
|
|
|
Example message::
|
|
|
|
{
|
|
"txid": "<sha3-256 hash>",
|
|
"assetid": "<sha3-256 hash>",
|
|
"blockid": "<sha3-256 hash>"
|
|
}
|
|
|
|
|
|
.. note::
|
|
|
|
Transactions in BigchainDB are validated in batches ("blocks") and will,
|
|
therefore, be streamed in batches. Each block can contain up to a 1000
|
|
transactions, ordered by the time at which they were included in the block.
|
|
The ``/valid_tx`` stream will send these transactions in the same order
|
|
that the block stored them in, but this does **NOT** guarantee that you
|
|
will recieve the events in that same order.
|