Event API
Abstract
This proposal describes the MQTT based Node Event API for IOTA nodes. Clients may subscribe to topics provided by the node, that acts as the message publisher and broker at the same time.
Motivation
The event API makes it possible for clients to implement event-based architectures as opposed to polling supported by the REST API defined in draft TIP-25.
The event-based architecture should be of great benefit to:
- wallets monitoring status of submitted blocks or transactions,
- explorers displaying the evolution of the Tangle and ledger state,
- archivers documenting the history of the Tangle.
Specification
The API is described using the AsyncAPI Specification:
Rationale
- MQTT is a lightweight protocol that is good at minimizing bandwidth and ensuring message delivery via Quality of Service.
- It may run on resource constrained devices as well and works on top of TCP/IP protocol.
- The publish-subscribe model makes information dissemination effective to interested clients only.
Backwards Compatibility
The previously employed event API described in TIP-16 is not backwards compatible with the current proposal, therefore versioning is introduced in the access URL of the API.
The response models are shared between the REST API and the event API.
The access route of the message broker should be updated to:
{nodeURL}/api/mqtt/v1
Reference Implementation
Broker
Client
- Go: https://github.com/iotaledger/iota.go/blob/develop/nodeclient/event_api_client.go
- Rust: https://github.com/iotaledger/iota.rs/tree/develop/client/src/node_api/mqtt
- TypeScript: https://github.com/iotaledger/iota.js/tree/feat/stardust/packages/mqtt
Copyright
Copyright and related rights waived via CC0.