From 4ec3c74737c77565d7332326d4acfd6bf6256802 Mon Sep 17 00:00:00 2001 From: Diane Huxley Date: Tue, 3 Oct 2023 10:20:34 -0700 Subject: [PATCH 1/2] Update README to reflect dwn-sdk-js 0.2.3 --- README.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7d2d55f75..721624e43 100644 --- a/README.md +++ b/README.md @@ -261,7 +261,12 @@ The query `request` contains the following properties: - **`from`** - _`DID string`_ (_optional_): the decentralized identifier of the DWeb Node the query will fetch results from. - **`message`** - _`object`_: the properties of the DWeb Node Message Descriptor that will be used to construct a valid record query: - **`filter`** - _`object`_: properties against which results of the query will be filtered: + - **`recordId`** - _`string`_ (_optional_): the record ID string that identifies the record data you are fetching. - **`protocol`** - _`URI string`_ (_optional_): the URI of the protocol bucket in which to query. + - **`protocolPath`** - _`string`_ (_optional_): the path to the record in the protocol configuration. + - **`contextId`** _`string`_ (_optional_): the `recordId` of a root record of a protocol. + - **`parentId`** _`string`_ (_optional_): the `recordId` of a the parent of a protocol record. + - **`recipient`** - _`string`_ (_optional_): the DID in the `recipient` field of the record. - **`schema`** - _`URI string`_ (_optional_): the URI of the schema bucket in which to query. - **`dataFormat`** - _`Media Type string`_ (_optional_): the IANA string corresponding with the format of the data to filter for. See IANA's Media Type list here: https://www.iana.org/assignments/media-types/media-types.xhtml @@ -311,13 +316,15 @@ The `create()` method is an alias for `write()` and both can take the same reque ### **`web5.dwn.records.read(request)`** -Method for reading a record stored in the user's local DWeb Node, remote DWeb Nodes, or another party's DWeb Nodes (if permitted). +Method for reading a record stored in the user's local DWeb Node, remote DWeb Nodes, or another party's DWeb Nodes (if permitted). The request takes a filter; if there is exactly one record matching the filter, the record and its data are returned. The most common filter is by `recordId`, but it is also useful to filter by `protocol`, `contextId`, and `protocolPath`. ```javascript // Reads the indicated record from the user's DWeb Nodes const { record } = await web5.dwn.records.read({ message: { - recordId: "bfw35evr6e54c4cqa4c589h4cq3v7w4nc534c9w7h5", + filter: { + recordId: "bfw35evr6e54c4cqa4c589h4cq3v7w4nc534c9w7h5", + } }, }); @@ -327,7 +334,9 @@ console.log(await record.data.text()); // assuming the record is a text payload, const { record } = await web5.dwn.records.read({ from: "did:example:bob", message: { - recordId: "bfw35evr6e54c4cqa4c589h4cq3v7w4nc534c9w7h5", + filter: { + recordId: "bfw35evr6e54c4cqa4c589h4cq3v7w4nc534c9w7h5", + } }, }); @@ -340,7 +349,15 @@ The `read` request object is composed as follows: - **`from`** - _`DID string`_ (_optional_): The DID of the DWeb Node the read request will fetch the indicated record from. - **`message`** - _`object`_: The properties of the DWeb Node Message Descriptor that will be used to construct a valid DWeb Node message. - - **`recordId`** - _`string`_: the required record ID string that identifies the record data you are fetching. + - **`filter`** - _`object`_: properties against which results of the query will be filtered: + - **`recordId`** - _`string`_ (_optional_): the record ID string that identifies the record data you are fetching. + - **`protocol`** - _`URI string`_ (_optional_): the URI of the protocol bucket in which to query. + - **`protocolPath`** - _`string`_ (_optional_): the path to the record in the protocol configuration. + - **`contextId`** _`string`_ (_optional_): the `recordId` of a root record of a protocol. + - **`parentId`** _`string`_ (_optional_): the `recordId` of a the parent of a protocol record. + - **`recipient`** - _`string`_ (_optional_): the DID in the `recipient` field of the record. + - **`schema`** - _`URI string`_ (_optional_): the URI of the schema bucket in which to query. + - **`dataFormat`** - _`Media Type string`_ (_optional_): the IANA string corresponding with the format of the data to filter for. See IANA's Media Type list here: https://www.iana.org/assignments/media-types/media-types.xhtml ### **`web5.dwn.records.delete(request)`** From 3d7fcd606f2a0953f473591d349d7b98b2f703d1 Mon Sep 17 00:00:00 2001 From: Diane Huxley Date: Tue, 3 Oct 2023 10:28:25 -0700 Subject: [PATCH 2/2] Update api/README.md --- packages/api/README.md | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/packages/api/README.md b/packages/api/README.md index a7eec6f6f..27f78caa6 100644 --- a/packages/api/README.md +++ b/packages/api/README.md @@ -209,7 +209,12 @@ The query `request` contains the following properties: - **`from`** - _`DID string`_ (_optional_): the decentralized identifier of the DWeb Node the query will fetch results from. - **`message`** - _`object`_: the properties of the DWeb Node Message Descriptor that will be used to construct a valid record query: - **`filter`** - _`object`_: properties against which results of the query will be filtered: + - **`recordId`** - _`string`_ (_optional_): the record ID string that identifies the record data you are fetching. - **`protocol`** - _`URI string`_ (_optional_): the URI of the protocol bucket in which to query. + - **`protocolPath`** - _`string`_ (_optional_): the path to the record in the protocol configuration. + - **`contextId`** _`string`_ (_optional_): the `recordId` of a root record of a protocol. + - **`parentId`** _`string`_ (_optional_): the `recordId` of a the parent of a protocol record. + - **`recipient`** - _`string`_ (_optional_): the DID in the `recipient` field of the record. - **`schema`** - _`URI string`_ (_optional_): the URI of the schema bucket in which to query. - **`dataFormat`** - _`Media Type string`_ (_optional_): the IANA string corresponding with the format of the data to filter for. See IANA's Media Type list here: https://www.iana.org/assignments/media-types/media-types.xhtml @@ -258,14 +263,15 @@ The `create` request object is composed as follows: The `create()` method is an alias for `write()` and both can take the same request object properties. ### **`web5.dwn.records.read(request)`** - -Method for reading a record stored in the user's local DWeb Node, remote DWeb Nodes, or another party's DWeb Nodes (if permitted). +Method for reading a record stored in the user's local DWeb Node, remote DWeb Nodes, or another party's DWeb Nodes (if permitted). The request takes a filter; if there is exactly one record matching the filter, the record and its data are returned. The most common filter is by `recordId`, but it is also useful to filter by `protocol`, `contextId`, and `protocolPath`. ```javascript // Reads the indicated record from the user's DWeb Nodes const { record } = await web5.dwn.records.read({ message: { - recordId: "bfw35evr6e54c4cqa4c589h4cq3v7w4nc534c9w7h5", + filter: { + recordId: "bfw35evr6e54c4cqa4c589h4cq3v7w4nc534c9w7h5", + } }, }); @@ -275,7 +281,9 @@ console.log(await record.data.text()); // assuming the record is a text payload, const { record } = await web5.dwn.records.read({ from: "did:example:bob", message: { - recordId: "bfw35evr6e54c4cqa4c589h4cq3v7w4nc534c9w7h5", + filter: { + recordId: "bfw35evr6e54c4cqa4c589h4cq3v7w4nc534c9w7h5", + } }, }); @@ -288,8 +296,15 @@ The `read` request object is composed as follows: - **`from`** - _`DID string`_ (_optional_): The DID of the DWeb Node the read request will fetch the indicated record from. - **`message`** - _`object`_: The properties of the DWeb Node Message Descriptor that will be used to construct a valid DWeb Node message. - - **`recordId`** - _`string`_: the required record ID string that identifies the record data you are fetching. - + - **`filter`** - _`object`_: properties against which results of the query will be filtered: + - **`recordId`** - _`string`_ (_optional_): the record ID string that identifies the record data you are fetching. + - **`protocol`** - _`URI string`_ (_optional_): the URI of the protocol bucket in which to query. + - **`protocolPath`** - _`string`_ (_optional_): the path to the record in the protocol configuration. + - **`contextId`** _`string`_ (_optional_): the `recordId` of a root record of a protocol. + - **`parentId`** _`string`_ (_optional_): the `recordId` of a the parent of a protocol record. + - **`recipient`** - _`string`_ (_optional_): the DID in the `recipient` field of the record. + - **`schema`** - _`URI string`_ (_optional_): the URI of the schema bucket in which to query. + - **`dataFormat`** - _`Media Type string`_ (_optional_): the IANA string corresponding with the format of the data to filter for. See IANA's Media Type list here: https://www.iana.org/assignments/media-types/media-types.xhtml ### **`web5.dwn.records.delete(request)`** Method for deleting a record stored in the user's local DWeb Node, remote DWeb Nodes, or another party's DWeb Nodes (if permitted).