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"