From a7b75bf0065db9d0430d4950cdac9776e108640f Mon Sep 17 00:00:00 2001 From: SionoiS Date: Wed, 27 Mar 2024 16:22:37 -0400 Subject: [PATCH] add store v3 --- api-spec/legacystoreapi.yaml | 137 +++++++++++++++++++++++++++++++++ api-spec/openapi.yaml | 4 + api-spec/schemas/apitypes.yaml | 36 +++++++++ api-spec/storeapi.yaml | 54 +++++++------ 4 files changed, 203 insertions(+), 28 deletions(-) create mode 100644 api-spec/legacystoreapi.yaml diff --git a/api-spec/legacystoreapi.yaml b/api-spec/legacystoreapi.yaml new file mode 100644 index 0000000..654f5cc --- /dev/null +++ b/api-spec/legacystoreapi.yaml @@ -0,0 +1,137 @@ +# /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: + - legacy_store + parameters: + - name: peerAddr + in: query + schema: + type: string + 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 diff --git a/api-spec/openapi.yaml b/api-spec/openapi.yaml index d7a2322..7649f65 100644 --- a/api-spec/openapi.yaml +++ b/api-spec/openapi.yaml @@ -21,6 +21,8 @@ tags: - 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. #TODO See [13/WAKU2-STORE]() RFC + - name: legacy_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 @@ -50,6 +52,8 @@ paths: /relay/v1/auto/subscriptions: $ref: "./relayapi_auto_subscriptions.yaml" /store/v1/messages: + $ref: "./legacystoreapi.yaml" + /store/v3/messages: $ref: "./storeapi.yaml" /filter/v1/subscriptions: $ref: "./filterapi_v1_subscriptions.yaml" diff --git a/api-spec/schemas/apitypes.yaml b/api-spec/schemas/apitypes.yaml index d82906b..50f3ef0 100644 --- a/api-spec/schemas/apitypes.yaml +++ b/api-spec/schemas/apitypes.yaml @@ -118,12 +118,48 @@ WakuMessage: format: int64 ephemeral: type: boolean + proof: + type: string meta: type: string format: byte required: - payload - contentTopic + - timestamp + +WakuMessageKeyValue: + type: object + properties: + message_hash: + type: string + message: + $ref: '#/components/schemas/WakuMessage' + required: + - message_hash + - message + +StoreQueryResponse: + type: object + properties: + request_id: + type: string + status_code: + type: integer + format: uint32 + status_desc: + type: string + messages: + type: array + items: + $ref: '#/components/schemas/WakuMessageKeyValue' + pagination_cursor: + type: string + required: + - request_id + - status_code + - status_desc + - messages PushRequest: type: object diff --git a/api-spec/storeapi.yaml b/api-spec/storeapi.yaml index f7f3379..542de74 100644 --- a/api-spec/storeapi.yaml +++ b/api-spec/storeapi.yaml @@ -1,8 +1,8 @@ -# /store/v1/messages: +# /store/v3/messages: get: summary: Gets message history description: > - Retrieves WakuV2 message history. The returned history + Retrieves Waku message history. The returned history can be potentially filtered by optional request parameters. operationId: getMessageHistory tags: @@ -12,11 +12,23 @@ get: 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: includeData + in: query + schema: + type: string + description: > + Boolean indicating if the query should return messages (data) or hashes only. + A value of 'false' returns hashes only. + A value of 'true' returns hashes AND messages. + Default value is 'false' + example: 'true' + - name: pubsubTopic in: query schema: @@ -60,38 +72,23 @@ get: integer value. example: '1680590945000000000' - - name: senderTime + - name: hashes 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' + Comma-separated list of message hashes. + URL-base64-encoded string computed as a hash of messages. + Used to find messages by hash. + example: 'Gc4ACThW5t2QQO82huq3WnDv%2FapPPJpD%2FwJfxDxAnR0%3D' - - name: storeTime + - name: cursor 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. + URL-base64-encoded string computed as a hash of a message. 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. @@ -110,16 +107,17 @@ get: schema: type: string description: > - "true" for paging forward, "false" for paging backward + "true" for paging forward, "false" for paging backward. + If not specified or if specified with an invalid value, the default is "true". example: "true" responses: '200': - description: WakuV2 message history. + description: Waku message history. content: application/json: schema: - $ref: './schemas/apitypes.yaml#/StoreResponse' + $ref: '#/components/schemas/StoreQueryResponse' '400': description: Bad request error. content: @@ -134,4 +132,4 @@ get: description: Internal server error. content: text/plain: - type: string + type: string \ No newline at end of file