From 23fd1ceb2f4734568f4d9254028b90bd267bdeb5 Mon Sep 17 00:00:00 2001 From: NagyZoltanPeter <113987313+NagyZoltanPeter@users.noreply.github.com> Date: Fri, 27 Oct 2023 13:01:14 +0200 Subject: [PATCH] Baseline commit, represents the state of openapi specification of nwaku as of v0.21.1 but restructured into one single specification. --- api-spec/adminapi.yaml | 37 ++++ api-spec/debugapi_info.yaml | 17 ++ api-spec/debugapi_version.yaml | 18 ++ api-spec/filterapi_v1_messages.yaml | 41 ++++ api-spec/filterapi_v1_subscriptions.yaml | 71 +++++++ api-spec/filterapi_v2_messages.yaml | 40 ++++ api-spec/filterapi_v2_subscription_ping.yaml | 42 +++++ api-spec/filterapi_v2_subscriptions.yaml | 126 +++++++++++++ api-spec/filterapi_v2_subscriptions_all.yaml | 38 ++++ api-spec/healthapi.yaml | 27 +++ api-spec/lightpushapi.yaml | 36 ++++ api-spec/openapi.yaml | 66 +++++++ api-spec/relayapi_auto_content_topic.yaml | 25 +++ api-spec/relayapi_auto_messages.yaml | 19 ++ api-spec/relayapi_auto_subscriptions.yaml | 50 +++++ api-spec/relayapi_messages.yaml | 51 +++++ api-spec/relayapi_subscriptions.yaml | 50 +++++ api-spec/schemas/apitypes.yaml | 189 +++++++++++++++++++ api-spec/storeapi.yaml | 138 ++++++++++++++ 19 files changed, 1081 insertions(+) create mode 100644 api-spec/adminapi.yaml create mode 100644 api-spec/debugapi_info.yaml create mode 100644 api-spec/debugapi_version.yaml create mode 100644 api-spec/filterapi_v1_messages.yaml create mode 100644 api-spec/filterapi_v1_subscriptions.yaml create mode 100644 api-spec/filterapi_v2_messages.yaml create mode 100644 api-spec/filterapi_v2_subscription_ping.yaml create mode 100644 api-spec/filterapi_v2_subscriptions.yaml create mode 100644 api-spec/filterapi_v2_subscriptions_all.yaml create mode 100644 api-spec/healthapi.yaml create mode 100644 api-spec/lightpushapi.yaml create mode 100644 api-spec/openapi.yaml create mode 100644 api-spec/relayapi_auto_content_topic.yaml create mode 100644 api-spec/relayapi_auto_messages.yaml create mode 100644 api-spec/relayapi_auto_subscriptions.yaml create mode 100644 api-spec/relayapi_messages.yaml create mode 100644 api-spec/relayapi_subscriptions.yaml create mode 100644 api-spec/schemas/apitypes.yaml create mode 100644 api-spec/storeapi.yaml diff --git a/api-spec/adminapi.yaml b/api-spec/adminapi.yaml new file mode 100644 index 0000000..596b540 --- /dev/null +++ b/api-spec/adminapi.yaml @@ -0,0 +1,37 @@ +get: + summary: Get connected peers info + description: Retrieve information about connected peers. + operationId: getPeerInfo + tags: + - admin + responses: + '200': + description: Information about a Waku v2 node. + content: + application/json: + schema: + type: array + items: + $ref: "./schemas/apitypes.yaml#/WakuPeer" + '5XX': + description: Unexpected error. +post: + summary: Adds new peer(s) to connect with + description: Adds new peer(s) to connect with. + operationId: postPeerInfo + tags: + - admin + requestBody: + content: + application/json: + schema: + type: array + items: + type: string + responses: + '200': + description: Ok + '400': + description: Cannot connect to one or more peers. + '5XX': + description: Unexpected error. diff --git a/api-spec/debugapi_info.yaml b/api-spec/debugapi_info.yaml new file mode 100644 index 0000000..56d7b24 --- /dev/null +++ b/api-spec/debugapi_info.yaml @@ -0,0 +1,17 @@ +get: + summary: Get node info + description: Retrieve information about a Waku v2 node. + operationId: getNodeInfo + tags: + - debug + responses: + '200': + description: Information about a Waku v2 node. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/WakuInfo' + '4XX': + description: Bad request error. + '5XX': + description: Unexpected error. diff --git a/api-spec/debugapi_version.yaml b/api-spec/debugapi_version.yaml new file mode 100644 index 0000000..85e06d5 --- /dev/null +++ b/api-spec/debugapi_version.yaml @@ -0,0 +1,18 @@ +get: + summary: Get node version + description: Retrieve the Waku v2 node version. + operationId: getNodeVersion + tags: + - debug + responses: + '200': + description: The version of a Waku v2 node. + content: + text/plain: + schema: + type: string + '4XX': + description: Bad request error. + '5XX': + description: Unexpected error. + diff --git a/api-spec/filterapi_v1_messages.yaml b/api-spec/filterapi_v1_messages.yaml new file mode 100644 index 0000000..2af80d3 --- /dev/null +++ b/api-spec/filterapi_v1_messages.yaml @@ -0,0 +1,41 @@ +# Legacy support for v1 waku filter +# /filter/v1/messages/{contentTopic}: +get: # get_waku_v2_filter_v1_messages + summary: Get the latest messages on the polled content topic + description: Get a list of messages that were received on a subscribed content topic after the last time this method was called. + operationId: getMessagesByTopic + tags: + - filter_legacy + parameters: + - in: path + name: contentTopic # Note the name is the same as in the path + required: true + schema: + type: string + description: Content topic of message + responses: + '200': + description: The latest messages on the polled topic. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterGetMessagesResponse' + # TODO: Review the possible errors of this endpoint + '400': + description: Bad request. + content: + text/plain: + schema: + type: string + '404': + description: Not found. + content: + text/plain: + schema: + type: string + '5XX': + description: Unexpected error. + content: + text/plain: + schema: + type: string diff --git a/api-spec/filterapi_v1_subscriptions.yaml b/api-spec/filterapi_v1_subscriptions.yaml new file mode 100644 index 0000000..4a946e2 --- /dev/null +++ b/api-spec/filterapi_v1_subscriptions.yaml @@ -0,0 +1,71 @@ +# Legacy support for v1 waku filter +# /filter/v1/subscriptions: +post: # post_waku_v2_filter_v1_subscription + summary: Subscribe a node to an array of topics + description: Subscribe a node to an array of content topics. + operationId: postSubscriptions + tags: + - filter_legacy + requestBody: + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterLegacySubscribeRequest' + responses: + '200': + description: OK + content: + text/plain: + schema: + type: string + # TODO: Review the possible errors of this endpoint + '400': + description: Bad request. + content: + text/plain: + schema: + type: string + '5XX': + description: Unexpected error. + content: + text/plain: + schema: + type: string + +delete: # delete_waku_v2_filter_v1_subscription + summary: Unsubscribe a node from an array of topics + description: Unsubscribe a node from an array of content topics. + operationId: deleteSubscriptions + tags: + - filter + requestBody: + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterLegacySubscribeRequest' + responses: + '200': + description: OK + content: + text/plain: + schema: + type: string + # TODO: Review the possible errors of this endpoint + '400': + description: Bad request. + content: + text/plain: + schema: + type: string + '404': + description: Not found. + content: + text/plain: + schema: + type: string + '5XX': + description: Unexpected error. + content: + text/plain: + schema: + type: string diff --git a/api-spec/filterapi_v2_messages.yaml b/api-spec/filterapi_v2_messages.yaml new file mode 100644 index 0000000..59dea60 --- /dev/null +++ b/api-spec/filterapi_v2_messages.yaml @@ -0,0 +1,40 @@ +# /filter/v2/messages/{contentTopic}: +get: # get_waku_v2_filter_v2_messages + summary: Get the latest messages on the polled content topic + description: Get a list of messages that were received on a subscribed content topic after the last time this method was called. + operationId: getMessagesByTopic + tags: + - filter + parameters: + - in: path + name: contentTopic # Note the name is the same as in the path + required: true + schema: + type: string + description: Content topic of message + responses: + '200': + description: The latest messages on the polled topic. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterGetMessagesResponse' + # TODO: Review the possible errors of this endpoint + '400': + description: Bad request. + content: + text/plain: + schema: + type: string + '404': + description: Not found. + content: + text/plain: + schema: + type: string + '5XX': + description: Unexpected error. + content: + text/plain: + schema: + type: string diff --git a/api-spec/filterapi_v2_subscription_ping.yaml b/api-spec/filterapi_v2_subscription_ping.yaml new file mode 100644 index 0000000..153de79 --- /dev/null +++ b/api-spec/filterapi_v2_subscription_ping.yaml @@ -0,0 +1,42 @@ +# /filter/v2/subscriptions/{requestId}: +get: # get_waku_v2_filter_v2_subscription - ping + summary: Subscriber-ping - a peer can query if there is a registered subscription for it + description: | + Subscriber peer can query its subscription existence on service node. + Returns HTTP200 if exists and HTTP404 if not. + Client must not fill anything but requestId in the request body. + operationId: subscriberPing + tags: + - filter + parameters: + - in: path + name: requestId + required: true + schema: + type: string + description: Id of ping request + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '400': + description: Bad request. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '404': + description: Not found. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '5XX': + description: Unexpected error. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' diff --git a/api-spec/filterapi_v2_subscriptions.yaml b/api-spec/filterapi_v2_subscriptions.yaml new file mode 100644 index 0000000..500387c --- /dev/null +++ b/api-spec/filterapi_v2_subscriptions.yaml @@ -0,0 +1,126 @@ +# /filter/v2/subscriptions: +post: # post_waku_v2_filter_v2_subscription + summary: Subscribe a peer to an array of content topics under a pubsubTopic + description: | + Subscribe a peer to an array of content topics under a pubsubTopic. + + It is allowed to refresh or add new content topic to an existing subscription. + + Fields pubsubTopic and contentFilters must be filled. + operationId: postSubscriptions + tags: + - filter + requestBody: + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscribeRequest' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + # TODO: Review the possible errors of this endpoint + '400': + description: Bad request. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '404': + description: Not found. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '5XX': + description: Unexpected error. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + +put: # put_waku_v2_filter_v2_subscription + summary: Modify existing subscription of a peer under a pubsubTopic + description: | + Modify existing subscription of a peer under a pubsubTopic. + + It is allowed to refresh or add new content topic to an existing subscription. + + Fields pubsubTopic and contentFilters must be filled. + operationId: putSubscriptions + tags: + - filter + requestBody: + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscribeRequest' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + # TODO: Review the possible errors of this endpoint + '400': + description: Bad request. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '404': + description: Not found. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '5XX': + description: Unexpected error. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + + +delete: # delete_waku_v2_filter_v2_subscription + summary: Unsubscribe a peer from content topics + description: | + Unsubscribe a peer from content topics + Only that subscription will be removed which matches existing. + operationId: deleteSubscriptions + tags: + - filter + requestBody: + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterUnsubscribeRequest' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '400': + description: Bad request. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '404': + description: Not found. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '5XX': + description: Unexpected error. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' diff --git a/api-spec/filterapi_v2_subscriptions_all.yaml b/api-spec/filterapi_v2_subscriptions_all.yaml new file mode 100644 index 0000000..6c5dc89 --- /dev/null +++ b/api-spec/filterapi_v2_subscriptions_all.yaml @@ -0,0 +1,38 @@ +# /filter/v2/subscriptions/all: +delete: # delete_waku_v2_filter_v2_subscription + summary: Unsubscribe a peer from all content topics + description: | + Unsubscribe a peer from all content topics + operationId: deleteAllSubscriptions + tags: + - filter + requestBody: + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterUnsubscribeAllRequest' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '400': + description: Bad request. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '404': + description: Not found. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' + '5XX': + description: Unexpected error. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/FilterSubscriptionResponse' diff --git a/api-spec/healthapi.yaml b/api-spec/healthapi.yaml new file mode 100644 index 0000000..6bd5400 --- /dev/null +++ b/api-spec/healthapi.yaml @@ -0,0 +1,27 @@ +get: + summary: Get node health status + description: Retrieve readiness of a Waku v2 node. + operationId: healthcheck + tags: + - health + responses: + '200': + description: Waku v2 node is up and running. + content: + text/plain: + schema: + type: string + example: Node is healty + '500': + description: Internal server error + content: + text/plain: + schema: + type: string + '503': + description: Node not initialized or having issues + content: + text/plain: + schema: + type: string + example: Node is not initialized diff --git a/api-spec/lightpushapi.yaml b/api-spec/lightpushapi.yaml new file mode 100644 index 0000000..6fc3524 --- /dev/null +++ b/api-spec/lightpushapi.yaml @@ -0,0 +1,36 @@ +post: + summary: Request a message relay from a LightPush service provider + description: Push a message to be relayed on a PubSub topic. + operationId: postMessagesToPubsubTopic + tags: + - lightpush + requestBody: + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/PushRequest' + responses: + '200': + description: OK + content: + text/plain: + schema: + type: string + '400': + description: Bad request. + content: + text/plain: + schema: + type: string + '500': + description: Internal server error + content: + text/plain: + schema: + type: string + '503': + description: Service not available + content: + text/plain: + schema: + type: string diff --git a/api-spec/openapi.yaml b/api-spec/openapi.yaml new file mode 100644 index 0000000..077462d --- /dev/null +++ b/api-spec/openapi.yaml @@ -0,0 +1,66 @@ +openapi: 3.0.3 +info: + title: Waku V2 node REST API + version: 1.0.0 + description: + contact: + name: VAC Team + url: https://forum.vac.dev/ + servers: + - url: http://localhost:8545 + description: Accessing your wakunode via API is possible normally via localhost on defaul port 8545. +tags: + - name: admin + description: Control of the connected peers. + - name: debug + description: Information about a Waku v2 node. + - name: health + description: Health check of a Waku v2 node. + - name: lightpush + description: Interface to request a message relay. See [19/WAKU2-LIGHTPUSH](https://rfc.vac.dev/spec/19/) RFC + - name: relay + description: Control of the relaying of messages. See [11/WAKU2-RELAY](https://rfc.vac.dev/spec/11/) RFC + - name: store + description: Retrieve the message history. See [13/WAKU2-STORE](https://rfc.vac.dev/spec/13/) RFC + - name: filter + 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. +paths: + /admin/v1/peers: + $ref: "./adminapi.yaml" + /debug/v1/info: + $ref: "./debugapi_info.yaml" + /debug/v1/version: + $ref: "./debugapi_version.yaml" + /health: + $ref: "./healthapi.yaml" + /lightpush/v1/message: + $ref: "./lightpushapi.yaml" + /relay/v1/messages/{pubsubTopic}: + $ref: "./relayapi_messages.yaml" + /relay/v1/subscriptions: + $ref: "./relayapi_subscriptions.yaml" + /relay/v1/auto/messages/{contentTopic}: + $ref: "./relayapi_auto_content_topic.yaml" + /relay/v1/auto/messages: + $ref: "./relayapi_auto_messages.yaml" + /relay/v1/auto/subscriptions: + $ref: "./relayapi_auto_subscriptions.yaml" + /store/v1/messages: + $ref: "./storeapi.yaml" + /filter/v1/subscriptions: + $ref: "./filterapi_v1_subscriptions.yaml" + /filter/v1/messages/{contentTopic}: + $ref: "./filterapi_v1_messages.yaml" + /filter/v2/subscriptions/{requestId}: + $ref: "./filterapi_v2_subscription_ping.yaml" + /filter/v2/subscriptions: + $ref: "./filterapi_v2_subscriptions.yaml" + /filter/v2/subscriptions/all: + $ref: "./filterapi_v2_subscriptions_all.yaml" + /filter/v2/messages/{contentTopic}: + $ref: "./filterapi_v2_messages.yaml" +components: + schemas: + $ref: "./schemas/apitypes.yaml" diff --git a/api-spec/relayapi_auto_content_topic.yaml b/api-spec/relayapi_auto_content_topic.yaml new file mode 100644 index 0000000..8cb06f0 --- /dev/null +++ b/api-spec/relayapi_auto_content_topic.yaml @@ -0,0 +1,25 @@ +# /relay/v1/auto/messages/{contentTopic}: # Note the plural in messages +get: # get_waku_v2_relay_v1_auto_messages + summary: Get the latest messages on the polled topic + description: Get a list of messages that were received on a subscribed Content topic after the last time this method was called. + operationId: getMessagesByTopic + tags: + - relay + parameters: + - in: path + name: contentTopic # Note the name is the same as in the path + required: true + schema: + type: string + description: The user ID + responses: + '200': + description: The latest messages on the polled topic. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/RelayGetMessagesResponse' + '4XX': + description: Bad request. + '5XX': + description: Unexpected error. diff --git a/api-spec/relayapi_auto_messages.yaml b/api-spec/relayapi_auto_messages.yaml new file mode 100644 index 0000000..741009c --- /dev/null +++ b/api-spec/relayapi_auto_messages.yaml @@ -0,0 +1,19 @@ +# /relay/v1/auto/messages: # Note the plural in messages +post: # post_waku_v2_relay_v1_auto_message + summary: Publish a message to be relayed + description: Publishes a message to be relayed on a Content topic. + operationId: postMessagesToTopic + tags: + - relay + requestBody: + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/RelayPostMessagesRequest' + responses: + '200': + description: OK + '4XX': + description: Bad request. + '5XX': + description: Unexpected error. diff --git a/api-spec/relayapi_auto_subscriptions.yaml b/api-spec/relayapi_auto_subscriptions.yaml new file mode 100644 index 0000000..74504c6 --- /dev/null +++ b/api-spec/relayapi_auto_subscriptions.yaml @@ -0,0 +1,50 @@ +# /relay/v1/auto/subscriptions: +post: # post_waku_v2_relay_v1_auto_subscriptions + summary: Subscribe a node to an array of topics + description: Subscribe a node to an array of Content topics. + operationId: postSubscriptions + tags: + - relay + 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_waku_v2_relay_v1_auto_subscriptions + summary: Unsubscribe a node from an array of topics + description: Unsubscribe a node from an array of Content topics. + operationId: deleteSubscriptions + tags: + - relay + 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/relayapi_messages.yaml b/api-spec/relayapi_messages.yaml new file mode 100644 index 0000000..898a1da --- /dev/null +++ b/api-spec/relayapi_messages.yaml @@ -0,0 +1,51 @@ +# /relay/v1/messages/{pubsubTopic}: # Note the plural in messages +get: # get_waku_v2_relay_v1_messages + summary: Get the latest messages on the polled topic + description: Get a list of messages that were received on a subscribed PubSub topic after the last time this method was called. + operationId: getMessagesByTopic + tags: + - relay + parameters: + - in: path + name: pubsubTopic # Note the name is the same as in the path + required: true + schema: + type: string + description: The user ID + responses: + '200': + description: The latest messages on the polled topic. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/RelayGetMessagesResponse' + '4XX': + description: Bad request. + '5XX': + description: Unexpected error. + +post: # post_waku_v2_relay_v1_message + summary: Publish a message to be relayed + description: Publishes a message to be relayed on a PubSub topic. + operationId: postMessagesToTopic + tags: + - relay + parameters: + - in: path + name: pubsubTopic # Note the name is the same as in the path + description: The messages content topic + required: true + schema: + $ref: './schemas/apitypes.yaml#/RelayPostMessagesRequest' + requestBody: + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/RelayPostMessagesRequest' + responses: + '200': + description: OK + '4XX': + description: Bad request. + '5XX': + description: Unexpected error. diff --git a/api-spec/relayapi_subscriptions.yaml b/api-spec/relayapi_subscriptions.yaml new file mode 100644 index 0000000..40bc3d0 --- /dev/null +++ b/api-spec/relayapi_subscriptions.yaml @@ -0,0 +1,50 @@ +# /relay/v1/subscriptions: +post: # post_waku_v2_relay_v1_subscriptions + summary: Subscribe a node to an array of topics + description: Subscribe a node to an array of PubSub topics. + operationId: postSubscriptions + tags: + - relay + requestBody: + content: + application/json: + schema: + type array: + items: + $ref: './schemas/apitypes.yaml#/PubsubTopic' + responses: + '200': + description: OK + content: + text/plain: + schema: + type: string + '4XX': + description: Bad request. + '5XX': + description: Unexpected error. + +delete: # delete_waku_v2_relay_v1_subscriptions + summary: Unsubscribe a node from an array of topics + description: Unsubscribe a node from an array of PubSub topics. + operationId: deleteSubscriptions + tags: + - relay + requestBody: + content: + application/json: + schema: + type array: + items: + $ref: './schemas/apitypes.yaml#/PubsubTopic' + responses: + '200': + description: OK + content: + text/plain: + schema: + type: string + '4XX': + description: Bad request. + '5XX': + description: Unexpected error. diff --git a/api-spec/schemas/apitypes.yaml b/api-spec/schemas/apitypes.yaml new file mode 100644 index 0000000..d5c0657 --- /dev/null +++ b/api-spec/schemas/apitypes.yaml @@ -0,0 +1,189 @@ +WakuPeer: + type: object + required: + - multiaddr + - protocols + properties: + multiaddr: + type: string + protocols: + type: array + items: + type: object + required: + - protocol + - connected + properties: + protocol: + type: string + connected: + type: boolean + +WakuInfo: + type: object + properties: + listenAddresses: + type: array + items: + type: string + enrUri: + type: string + required: + - listenAddresses + +PubsubTopic: + type: string +ContentTopic: + type: string + +FilterLegacySubscribeRequest: + type: object + properties: + contentFilters: + type: array + items: + $ref: '#/ContentTopic' + pubsubTopic: + $ref: "#/PubsubTopic" + required: + - contentFilters + +FilterGetMessagesResponse: + type: array + items: + $ref: '#/WakuMessage' + +FilterSubscribeRequest: + type: object + properties: + requestId: + type: string + contentFilters: + type: array + items: + $ref: '#/ContentTopic' + pubsubTopic: + $ref: "#/PubsubTopic" + required: + - requestId + - contentFilters + - pubsubTopic + +FilterUnsubscribeRequest: + type: object + properties: + requestId: + type: string + contentFilters: + type: array + items: + $ref: '#/ContentTopic' + pubsubTopic: + $ref: "#/PubsubTopic" + required: + - requestId + - contentFilters + +FilterUnsubscribeAllRequest: + type: object + properties: + requestId: + type: string + required: + - requestId + +FilterSubscriptionResponse: + type: object + properties: + requestId: + type: string + statusDesc: + type: string + required: + - requestId + +WakuMessage: + type: object + properties: + payload: + type: string + format: byte + contentTopic: + $ref: '#/ContentTopic' + version: + type: integer + format: int32 + timestamp: + type: integer + format: int64 + ephemeral: + type: boolean + required: + - payload + - contentTopic + +PushRequest: + type: object + properties: + pusbsubTopic: + $ref: '#/PubsubTopic' + message: + $ref: '#/WakuMessage' + required: + - message + +## TODO: Check if it can be tunneled into the one WakuMessage structure +## mainly because of Relay post message request can break in client code +RelayWakuMessage: + type: object + properties: + payload: + type: string + format: byte + contentTopic: + $ref: '#/ContentTopic' + version: + type: number + timestamp: + type: number + required: + - payload + +RelayGetMessagesResponse: + type: array + items: + $ref: '#/RelayWakuMessage' + +RelayPostMessagesRequest: + $ref: '#/RelayWakuMessage' + +StoreResponse: + type: object + properties: + messages: + type: array + items: + $ref: '#/WakuMessage' + cursor: + $ref: '#/HistoryCursor' + error_message: + type: string + required: + - messages + +HistoryCursor: + type: object + properties: + pubsub_topic: + type: string + sender_time: + type: string + store_time: + type: string + digest: + type: string + required: + - pubsub_topic + - sender_time + - store_time + - digest diff --git a/api-spec/storeapi.yaml b/api-spec/storeapi.yaml new file mode 100644 index 0000000..42dd227 --- /dev/null +++ b/api-spec/storeapi.yaml @@ -0,0 +1,138 @@ +# /store/v1/messages: +get: + summary: Gets message history + description: > + Retrieves WakuV2 message history. The returned history + can be potentially filtered by optional request parameters. + operationId: getMessageHistory + tags: + - store + parameters: + - name: peerAddr + in: query + schema: + type: string + required: true + description: > + P2P fully qualified peer multiaddress + in the format `(ip4|ip6)/tcp/p2p/$peerId` and URL-encoded. + example: '%2Fip4%2F127.0.0.1%2Ftcp%2F60001%2Fp2p%2F16Uiu2HAmVFXtAfSj4EiR7mL2KvL4EE2wztuQgUSBoj2Jx2KeXFLN' + + - name: pubsubTopic + in: query + schema: + type: string + description: > + The pubsub topic on which a WakuMessage is published. + If left empty, no filtering is applied. + It is also intended for pagination purposes. + It should be a URL-encoded string. + example: 'my%20pubsub%20topic' + + - name: contentTopics + in: query + schema: string + description: > + Comma-separated list of content topics. When specified, + only WakuMessages that are linked to any of the given + content topics will be delivered in the get response. + It should be a URL-encoded-comma-separated string. + example: 'my%20first%20content%20topic%2Cmy%20second%20content%20topic%2Cmy%20third%20content%20topic' + + - name: startTime + in: query + schema: + type: string + description: > + The inclusive lower bound on the timestamp of + queried WakuMessages. This field holds the + Unix epoch time in nanoseconds as a 64-bits + integer value. + example: '1680590945000000000' + + - name: endTime + in: query + schema: + type: string + description: > + The inclusive upper bound on the timestamp of + queried WakuMessages. This field holds the + Unix epoch time in nanoseconds as a 64-bits + integer value. + example: '1680590945000000000' + + - name: senderTime + in: query + schema: + type: string + description: > + Cursor field intended for pagination purposes. + Represents the Unix time in nanoseconds at which a message was generated. + It could be empty for retrieving the first page, + and will be returned from the GET response so that + it can be part of the next page request. + example: '1680590947000000000' + + - name: storeTime + in: query + schema: + type: string + description: > + Cursor field intended for pagination purposes. + Represents the Unix time in nanoseconds at which a message was stored. + It could be empty for retrieving the first page, + and will be returned from the GET response so that + it can be part of the next page request. + example: '1680590945000000000' + + - name: digest + in: query + schema: + type: string + description: > + Cursor field intended for pagination purposes. + URL-base64-encoded string computed as a hash of the + a message content topic plus a message payload. + It could be empty for retrieving the first page, + and will be returned from the GET response so that + it can be part of the next page request. + example: 'Gc4ACThW5t2QQO82huq3WnDv%2FapPPJpD%2FwJfxDxAnR0%3D' + + - name: pageSize + in: query + schema: + type: string + description: > + Number of messages to retrieve per page + example: '5' + + - name: ascending + in: query + schema: + type: string + description: > + "true" for paging forward, "false" for paging backward + example: "true" + + responses: + '200': + description: WakuV2 message history. + content: + application/json: + schema: + $ref: './schemas/apitypes.yaml#/StoreResponse' + '400': + description: Bad request error. + content: + text/plain: + type: string + '412': + description: Precondition failed. + content: + text/plain: + type: string + '500': + description: Internal server error. + content: + text/plain: + type: string