Skip to content

Commit 218ec04

Browse files
authored
feat: high level feeds api documentation (#55)
1 parent f734daa commit 218ec04

File tree

1 file changed

+36
-3
lines changed

1 file changed

+36
-3
lines changed

docs/user-documentation/soc-and-feeds.md

Lines changed: 36 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,40 @@ In Swarm, `topic` is a 32-byte long arbitrary byte array. It's possible to choos
113113
const topic = bee.makeFeedTopic('my-dapp.eth/outbox')
114114
```
115115

116-
### Reading feeds
116+
### High level JSON API
117+
118+
Many applications are storing or manipulating data in JSON. bee-js has convenience high level API to use feeds with JSON objects.
119+
It consists of two methods:
120+
121+
- [`setJsonFeed`](../api/classes/bee.md#setjsonfeed) method to set JSON compatible data to feed
122+
- [`getJsonFeed`](../api/classes/bee.md#getjsonfeed) method to get JSON compatible data (and parse them) from feed
123+
124+
:::info Bee's instance signer
125+
You can pass a [`Signer`](../api/types/signer.md) (or compatible data) into [`Bee` class constructor](../api/classes/bee.md#constructor), which then
126+
will be used as default `Signer`.
127+
:::
128+
129+
```js
130+
await bee.setJsonFeed(
131+
'some cool arbitraty topic',
132+
{ some: ['cool', { json: 'compatible' }, 'object']},
133+
{ signer: '0x634fb5a872396d9693e5c9f9d7233cfa93f395c093371017ff44aa9ae6564cdd' }
134+
)
135+
136+
const data = await bee.getJsonFeed(
137+
'some cool arbitraty topic',
138+
{ signer: '0x634fb5a872396d9693e5c9f9d7233cfa93f395c093371017ff44aa9ae6564cdd' }
139+
)
140+
141+
console.log(data)
142+
// Prints: { some: ['cool', { json: 'compatible' }, 'object']}
143+
```
144+
145+
### Low level API
146+
147+
Low level API is an API that is more flexible in its usage, but requires better understanding and mainly more method calls.
148+
149+
#### Reading feeds
117150

118151
To read data from a feed, we need to make a reader object for a specific `type`, `topic` and `owner`, then we can download the latest update containing a reference.
119152

@@ -125,7 +158,7 @@ const feedUpdate = await feedReader.download()
125158
console.log(feedUpdate.reference) // prints the latest reference stored in the feed
126159
```
127160

128-
### Writing feeds
161+
#### Writing feeds
129162

130163
When writing a feed, typically an immutable content is uploaded first, and then its reference is updated in the feed. The `signer` here is the same as with [writing the SOCs](#writing-socs) (with the same caveats!).
131164

@@ -142,7 +175,7 @@ const response = await feedWriter.upload(reference)
142175

143176
One of the most common use cases for feeds is to store mutable data in an immutable address. For example, when hosting a website on Swarm, we may want its address stored in ENS, but we don't want to pay for changing the reference every time the site is updated.
144177

145-
Swarm provides a feature called `feed manifests` for this use case. It is a content-addressed chunk that stores a feed's definition (the `type`, the `topic`, and the `owner`). When it is looked up using the `bzz` endpoint, Swarm recognizes that it refers to a feed and continues the lookup according to the feed parameters.
178+
Swarm provides a feature called "feed manifests" for this use case. It is a content-addressed chunk that stores a feed's definition (the `type`, the `topic`, and the `owner`). When it is looked up using the `bzz` endpoint, Swarm recognizes that it refers to a feed and continues the lookup according to the feed parameters.
146179

147180
```js
148181
const topic = '0000000000000000000000000000000000000000000000000000000000000000'

0 commit comments

Comments
 (0)