From 23059b7c0be2d471e84fc47ab904fef320d4d6c1 Mon Sep 17 00:00:00 2001 From: NagyZoltanPeter <113987313+NagyZoltanPeter@users.noreply.github.com> Date: Thu, 16 Jul 2026 17:22:09 +0200 Subject: [PATCH 1/2] feat: add messaging REST API spec Document the high-level messaging client REST surface following the existing per-endpoint-file structure: - POST/DELETE /messaging/v1/subscriptions (subscribe by content topic) - POST /messaging/v1/messages (send a MessageEnvelope -> requestId) - GET /messaging/v1/events/send[/{requestId}] (poll send events) - GET /messaging/v1/events/received (poll received messages) Adds the messaging schemas to schemas/apitypes.yaml (MessagingJsonEnvelope, MessagingSendResponse, SendEventRecord, SendStatus, ReceivedMessageRecord, list wrappers) and wires the paths + a `messaging` tag into openapi.yaml. Co-Authored-By: Claude Opus 4.8 --- api-spec/messagingapi_events_received.yaml | 16 ++++ api-spec/messagingapi_events_send.yaml | 16 ++++ api-spec/messagingapi_events_send_by_id.yaml | 27 ++++++ api-spec/messagingapi_messages.yaml | 23 ++++++ api-spec/messagingapi_subscriptions.yaml | 50 +++++++++++ api-spec/openapi.yaml | 12 +++ api-spec/schemas/apitypes.yaml | 87 ++++++++++++++++++++ 7 files changed, 231 insertions(+) create mode 100644 api-spec/messagingapi_events_received.yaml create mode 100644 api-spec/messagingapi_events_send.yaml create mode 100644 api-spec/messagingapi_events_send_by_id.yaml create mode 100644 api-spec/messagingapi_messages.yaml create mode 100644 api-spec/messagingapi_subscriptions.yaml diff --git a/api-spec/messagingapi_events_received.yaml b/api-spec/messagingapi_events_received.yaml new file mode 100644 index 0000000..05f7c60 --- /dev/null +++ b/api-spec/messagingapi_events_received.yaml @@ -0,0 +1,16 @@ +# /messaging/v1/events/received: +get: # get_messaging_v1_events_received + summary: Poll buffered received messages + description: Returns buffered received messages (up to the cache capacity, oldest first), then clears them (evict-after-poll). Optimized for polling; each record carries the message hash and the full received WakuMessage. + operationId: getMessagingReceivedMessages + tags: + - messaging + responses: + '200': + description: The buffered received messages, oldest first. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/ReceivedMessagesResponse' + '5XX': + description: Unexpected error. diff --git a/api-spec/messagingapi_events_send.yaml b/api-spec/messagingapi_events_send.yaml new file mode 100644 index 0000000..9bc1c76 --- /dev/null +++ b/api-spec/messagingapi_events_send.yaml @@ -0,0 +1,16 @@ +# /messaging/v1/events/send: +get: # get_messaging_v1_events_send + summary: Poll all buffered send events + description: Returns all buffered send events grouped by request id, then clears them (evict-after-poll). Send events are buffered because REST is a poll-based surface over the interactive MessagingClient events. + operationId: getMessagingSendEvents + tags: + - messaging + responses: + '200': + description: The buffered send events, grouped by request id. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/SendStatusList' + '5XX': + description: Unexpected error. diff --git a/api-spec/messagingapi_events_send_by_id.yaml b/api-spec/messagingapi_events_send_by_id.yaml new file mode 100644 index 0000000..f358f03 --- /dev/null +++ b/api-spec/messagingapi_events_send_by_id.yaml @@ -0,0 +1,27 @@ +# /messaging/v1/events/send/{requestId}: +get: # get_messaging_v1_events_send_by_id + summary: Poll the send events for one request id + description: Returns the buffered send events for a single request id, then removes them (evict-after-poll). The request id is the value returned by POST /messaging/v1/messages. + operationId: getMessagingSendEventsById + tags: + - messaging + parameters: + - in: path + name: requestId # Note the name is the same as in the path + required: true + schema: + type: string + description: The request id returned by the send endpoint. + responses: + '200': + description: The buffered send events for the request id. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/SendStatus' + '404': + description: No send events buffered for the given request id. + '4XX': + description: Bad request. + '5XX': + description: Unexpected error. diff --git a/api-spec/messagingapi_messages.yaml b/api-spec/messagingapi_messages.yaml new file mode 100644 index 0000000..8fa74f9 --- /dev/null +++ b/api-spec/messagingapi_messages.yaml @@ -0,0 +1,23 @@ +# /messaging/v1/messages: +post: # post_messaging_v1_messages + summary: Send a message through the messaging client + description: Sends a message (a MessageEnvelope) through the messaging client and returns the request id used to correlate the subsequent send events. + operationId: postMessagingMessage + tags: + - messaging + requestBody: + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/MessagingJsonEnvelope' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/MessagingSendResponse' + '4XX': + description: Bad request. + '5XX': + description: Unexpected error. diff --git a/api-spec/messagingapi_subscriptions.yaml b/api-spec/messagingapi_subscriptions.yaml new file mode 100644 index 0000000..496f986 --- /dev/null +++ b/api-spec/messagingapi_subscriptions.yaml @@ -0,0 +1,50 @@ +# /messaging/v1/subscriptions: +post: # post_messaging_v1_subscriptions + summary: Subscribe the messaging client to an array of content topics + description: Subscribe the messaging client to an array of Content topics. + operationId: postMessagingSubscriptions + tags: + - messaging + requestBody: + content: + application/json: + schema: + type: array + items: + $ref: './schemas/apitypes.yaml#/ContentTopic' + responses: + '200': + description: OK + content: + text/plain: + schema: + type: string + '4XX': + description: Bad request. + '5XX': + description: Unexpected error. + +delete: # delete_messaging_v1_subscriptions + summary: Unsubscribe the messaging client from an array of content topics + description: Unsubscribe the messaging client from an array of Content topics. + operationId: deleteMessagingSubscriptions + tags: + - messaging + requestBody: + content: + application/json: + schema: + type: array + items: + $ref: './schemas/apitypes.yaml#/ContentTopic' + responses: + '200': + description: OK + content: + text/plain: + schema: + type: string + '4XX': + description: Bad request. + '5XX': + description: Unexpected error. diff --git a/api-spec/openapi.yaml b/api-spec/openapi.yaml index b2fe734..6ea369c 100644 --- a/api-spec/openapi.yaml +++ b/api-spec/openapi.yaml @@ -28,6 +28,8 @@ tags: description: Control of the content filtering. See [12/WAKU2-FILTER](https://rfc.vac.dev/spec/12/) RFC - name: filter_legacy description: Obsolate Filter interface kept for compatibility reason. Will be removed in future. + - name: messaging + description: High-level messaging client interface (subscribe / send by content topic) and poll-based observation of send and received events. paths: /health: $ref: "./healthapi.yaml" @@ -89,6 +91,16 @@ paths: $ref: "./filterapi_v2_subscriptions_all.yaml" /filter/v2/messages/{contentTopic}: $ref: "./filterapi_v2_messages.yaml" + /messaging/v1/subscriptions: + $ref: "./messagingapi_subscriptions.yaml" + /messaging/v1/messages: + $ref: "./messagingapi_messages.yaml" + /messaging/v1/events/send: + $ref: "./messagingapi_events_send.yaml" + /messaging/v1/events/send/{requestId}: + $ref: "./messagingapi_events_send_by_id.yaml" + /messaging/v1/events/received: + $ref: "./messagingapi_events_received.yaml" components: schemas: $ref: "./schemas/apitypes.yaml" diff --git a/api-spec/schemas/apitypes.yaml b/api-spec/schemas/apitypes.yaml index 544b9b9..e1857b5 100644 --- a/api-spec/schemas/apitypes.yaml +++ b/api-spec/schemas/apitypes.yaml @@ -320,3 +320,90 @@ HealthReport: type: object additionalProperties: $ref: "#/HealthStatus" + +## Messaging API types + +MessagingJsonEnvelope: + type: object + description: JSON wire form of the messaging MessageEnvelope (the send input). + properties: + payload: + type: string + format: byte + contentTopic: + $ref: "#/ContentTopic" + ephemeral: + type: boolean + meta: + type: string + format: byte + required: + - payload + - contentTopic + +MessagingSendResponse: + type: object + properties: + requestId: + type: string + description: Correlates the send with its MessageSent / MessageError events. + required: + - requestId + +SendEventRecord: + type: object + properties: + kind: + type: string + enum: + - "sent" + - "propagated" + - "error" + messageHash: + type: string + error: + type: string + description: Populated only when kind is "error". + timestamp: + type: integer + format: int64 + description: Nanoseconds, stamped when the event was cached. + required: + - kind + - messageHash + - timestamp + +SendStatus: + type: object + description: All send events observed so far for a single request id. + properties: + requestId: + type: string + events: + type: array + items: + $ref: "#/SendEventRecord" + required: + - requestId + - events + +SendStatusList: + type: array + items: + $ref: "#/SendStatus" + +ReceivedMessageRecord: + type: object + properties: + messageHash: + type: string + message: + $ref: "#/RelayWakuMessage" + required: + - messageHash + - message + +ReceivedMessagesResponse: + type: array + items: + $ref: "#/ReceivedMessageRecord" From c762ccaa918b27bea3e03c4a510dcf4689f337a6 Mon Sep 17 00:00:00 2001 From: NagyZoltanPeter <113987313+NagyZoltanPeter@users.noreply.github.com> Date: Thu, 16 Jul 2026 15:45:45 +0000 Subject: [PATCH 2/2] From Waku v2 to Logos Delivery - refresh naming --- README.md | 2 +- api-spec/adminapi_log_level.yaml | 2 +- api-spec/adminapi_peer.yaml | 2 +- api-spec/adminapi_peers_stats.yaml | 2 +- api-spec/debugapi_info.yaml | 4 ++-- api-spec/debugapi_version.yaml | 4 ++-- api-spec/healthapi.yaml | 4 ++-- api-spec/openapi.yaml | 6 +++--- 8 files changed, 13 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 51fd7e8..40cd9c1 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,2 @@ # waku-rest-api -Open API specification of Waku v2 client interface +Open API specification of Logos Delivery client interface diff --git a/api-spec/adminapi_log_level.yaml b/api-spec/adminapi_log_level.yaml index 835bef4..871b907 100644 --- a/api-spec/adminapi_log_level.yaml +++ b/api-spec/adminapi_log_level.yaml @@ -1,6 +1,6 @@ post: summary: Dynamic set log level on the node - description: Change the log level of a Waku v2 node. + description: Change the log level of a Logos Delivery node. operationId: setLogLevel tags: - admin diff --git a/api-spec/adminapi_peer.yaml b/api-spec/adminapi_peer.yaml index 50bc34f..a74f477 100644 --- a/api-spec/adminapi_peer.yaml +++ b/api-spec/adminapi_peer.yaml @@ -13,7 +13,7 @@ get: description: ID of the peer to retrieve information for responses: '200': - description: Information about a Waku v2 node. + description: Information about a Logos Delivery node. content: application/json: schema: diff --git a/api-spec/adminapi_peers_stats.yaml b/api-spec/adminapi_peers_stats.yaml index e6042ae..e527cd5 100644 --- a/api-spec/adminapi_peers_stats.yaml +++ b/api-spec/adminapi_peers_stats.yaml @@ -6,7 +6,7 @@ get: - admin responses: '200': - description: Information about a Waku v2 node. + description: Information about a Logos Delivery node. content: application/json: schema: diff --git a/api-spec/debugapi_info.yaml b/api-spec/debugapi_info.yaml index 56d7b24..485af9c 100644 --- a/api-spec/debugapi_info.yaml +++ b/api-spec/debugapi_info.yaml @@ -1,12 +1,12 @@ get: summary: Get node info - description: Retrieve information about a Waku v2 node. + description: Retrieve information about a Logos Delivery node. operationId: getNodeInfo tags: - debug responses: '200': - description: Information about a Waku v2 node. + description: Information about a Logos Delivery node. content: application/json: schema: diff --git a/api-spec/debugapi_version.yaml b/api-spec/debugapi_version.yaml index 85e06d5..588e32a 100644 --- a/api-spec/debugapi_version.yaml +++ b/api-spec/debugapi_version.yaml @@ -1,12 +1,12 @@ get: summary: Get node version - description: Retrieve the Waku v2 node version. + description: Retrieve the Logos Delivery node version. operationId: getNodeVersion tags: - debug responses: '200': - description: The version of a Waku v2 node. + description: The version of a Logos Delivery node. content: text/plain: schema: diff --git a/api-spec/healthapi.yaml b/api-spec/healthapi.yaml index 5763162..ca3e54d 100644 --- a/api-spec/healthapi.yaml +++ b/api-spec/healthapi.yaml @@ -1,12 +1,12 @@ get: summary: Get node health status - description: Retrieve status of a Waku v2 node. + description: Retrieve status of a Logos Delivery node. operationId: healthcheck tags: - health responses: '200': - description: Health report of a Waku v2 node and its protocols. + description: Health report of a Logos Delivery node and its protocols. content: application/json: schema: diff --git a/api-spec/openapi.yaml b/api-spec/openapi.yaml index 6ea369c..8c312af 100644 --- a/api-spec/openapi.yaml +++ b/api-spec/openapi.yaml @@ -1,6 +1,6 @@ openapi: 3.1.0 info: - title: Waku V2 node REST API + title: Logos Delivery node REST API version: 1.0.0 description: contact: @@ -13,9 +13,9 @@ tags: - name: admin description: Control of the connected peers. - name: debug - description: Information about a Waku v2 node. + description: Information about a Logos Delivery node. - name: health - description: Health check of a Waku v2 node. + description: Health check of a Logos Delivery node. - name: lightpush description: Interface to request a message relay. See [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/) RFC - name: relay