tip: 28
title: Event API
description: Node event API definitions in AsyncAPI Specification
author: Luca Moser (@luca-moser) , Levente Pap (@lzpap) 
discussions-to: https://github.com/iotaledger/tips/pull/33, https://github.com/iotaledger/tips/pull/66
status: Active
type: Standards
layer: Interface
created: 2022-03-02
replaces: 16

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:

AsyncAPI Editor

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

  • https://github.com/gohornet/inx-mqtt

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 and related rights waived via CC0.