From 0b33a408e6dbdb974fbb1294dfd2bb1bc3bed981 Mon Sep 17 00:00:00 2001
From: Eugen Rochko <eugen@zeonfederated.com>
Date: Tue, 25 Sep 2018 02:09:46 +0200
Subject: [PATCH] Add Streaming API and Web Push API documentation

---
 content/en/api/push.md      | 14 +++++++
 content/en/api/streaming.md | 78 +++++++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 content/en/api/push.md
 create mode 100644 content/en/api/streaming.md

diff --git a/content/en/api/push.md b/content/en/api/push.md
new file mode 100644
index 00000000..23148ef1
--- /dev/null
+++ b/content/en/api/push.md
@@ -0,0 +1,14 @@
+---
+title: Web Push API
+menu:
+  docs:
+    parent: api
+    weight: 5
+---
+
+Mastodon natively supports the [Web Push API](https://developer.mozilla.org/en-US/docs/Web/API/Push_API). You can utilize the same mechanisms for your native app. For a reference, see [Mozilla's web push server](https://github.com/mozilla-services/autopush), and more practically, see:
+
+- [toot-relay](https://github.com/DagAgren/toot-relay)
+- [PushToFCM](https://github.com/tateisu/PushToFCM)
+
+Using the Web Push API requires your app to have the `push` scope.
diff --git a/content/en/api/streaming.md b/content/en/api/streaming.md
new file mode 100644
index 00000000..52d975d5
--- /dev/null
+++ b/content/en/api/streaming.md
@@ -0,0 +1,78 @@
+---
+title: Streaming API
+menu:
+  docs:
+    parent: api
+    weight: 4
+---
+
+Your application can use a [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) endpoint to receive updates in real-time. Server-sent events is an incredibly simple transport method that relies entirely on chunked-encoding transfer, i.e. the HTTP connection is kept open and receives new data periodically.
+
+Alternatively, a WebSocket connection can also be established.
+
+## HTTP
+### Endpoints
+
+**GET /api/v1/streaming/user**
+
+Returns events that are relevant to the authorized user, i.e. home timeline and notifications
+
+**GET /api/v1/streaming/public**
+
+Returns all public statuses
+
+**GET /api/v1/streaming/public/local**
+
+Returns all local statuses
+
+**GET /api/v1/streaming/hashtag**
+
+Returns all public statuses for a particular hashtag (query param `tag`)
+
+**GET /api/v1/streaming/hashtag/local**
+
+Returns all local statuses for a particular hashtag (query param `tag`)
+
+**GET /api/v1/streaming/list**
+
+Returns statuses for a list (query param `list`)
+
+**GET /api/v1/streaming/direct**
+
+Returns all direct messages
+
+### Stream contents
+
+The stream will contain events as well as heartbeat comments. Lines that begin with a colon (`:`) can be ignored by parsers, they are simply there to keep the connection open. Events have this structure:
+
+```
+event: name
+data: payload
+```
+
+## WebSocket
+
+For WebSockets, there is only one URL path (`/api/v1/streaming`). The access token as well as the endpoint you are interested in must be provided with query params, respectively `access_token` and `stream`. Query params `list` and `tag` are likewise supported for relevant endpoints.
+
+Possible `stream` values:
+
+- `user`
+- `public`
+- `public:local`
+- `hashtag`
+- `hashtag:local`
+- `list`
+- `direct`
+
+## Event types
+
+|Event|Description|What's in the payload|
+|-----|-----------|---------------------|
+|`update`|A new status has appeared!|Status|
+|`notification`|A new notification|Notification|
+|`delete`|A status has been deleted|ID of the deleted status|
+|`filters_changed`|Keyword filters have been changed||
+
+The payload is JSON-encoded.
+
+> **Note:** In case of `filters_changed` event, `payload` is not defined.