nwaku/docs/api/v2/node.md
Oskar Thorén 3c11734bbf
Simplify Node API (#77)
* Waku v2 Node API: Split into implemented and NYI

- Init is now separated into Create and Start node

* Simplify Node API

* Node API: proc->method and add WakuNode as first argument

* Fix indent to make compile

* Stub out all API methods
2020-07-27 17:01:06 +08:00

78 lines
2.7 KiB
Markdown

# Waku APIs
## Nim API
The Nim Waku API consist of five methods. Some of them have different arity
depending on what privacy/bandwidth trade-off the consumer wants to make. These
five method are:
1. **Init** - create and start a node.
2. **Subscribe** - to a topic or a specific content filter.
3. **Unsubscribe** - to a topic or a specific content filter.
4. **Publish** - to a topic, or a topic and a specific content filter.
5. **Query** - for historical messages.
```Nim
proc init*(conf: WakuNodeConf): Future[WakuNode]
## Creates and starts a Waku node.
##
## Status: Partially implemented.
## TODO Take conf as a parameter and return a started WakuNode
method subscribe*(w: WakuNode, topic: Topic, handler: TopicHandler)
## Subscribes to a PubSub topic. Triggers handler when receiving messages on
## this topic. TopicHandler is a method that takes a topic and a `Message`.
##
## Status: Not yet implemented.
## TODO Implement as wrapper around `waku_protocol`, and ensure Message is
## passed, not `data` field.
method subscribe*(w: WakuNode, contentFilter: ContentFilter, handler: ContentFilterHandler)
## Subscribes to a ContentFilter. Triggers handler when receiving messages on
## this content filter. ContentFilter is a method that takes some content
## filter, specifically with `ContentTopic`, and a `Message`. The `Message`
## has to match the `ContentTopic`.
## Status: Not yet implemented.
## TODO Implement as wrapper around `waku_protocol` and `subscribe` above, and
## ensure Message is passed, not `data` field.
method unsubscribe*(w: WakuNode, topic: Topic)
## Unsubscribe from a topic.
##
## Status: Not yet implemented.
## TODO Implement.
method unsubscribe*(w: WakuNode, contentFilter: ContentFilter)
## Unsubscribe from a content filter.
##
## Status: Not yet implemented.
## TODO Implement.
method publish*(w: WakuNode, topic: Topic, message: Message)
## Publish a `Message` to a PubSub topic.
##
## Status: Not yet implemented.
## TODO Implement as wrapper around `waku_protocol`, and ensure Message is
## passed, not `data` field.
method publish*(w: WakuNode, topic: Topic, contentFilter: ContentFilter, message: Message)
## Publish a `Message` to a PubSub topic with a specific content filter.
## Currently this means a `contentTopic`.
##
## Status: Not yet implemented.
## TODO Implement as wrapper around `waku_protocol` and `publish`, and ensure
## Message is passed, not `data` field. Also ensure content filter is in
## Message.
method query*(w: WakuNode, query: HistoryQuery): HistoryResponse
## Queries for historical messages.
##
## Status: Not yet implemented.
## TODO Implement as wrapper around `waku_protocol` and send `RPCMsg`.
```
## JSON RPC
### TODO To specify