diff options
| -rw-r--r-- | docs/README.md | 1 | ||||
| -rw-r--r-- | docs/Using-the-API/Streaming-API.md | 40 | ||||
| -rw-r--r-- | streaming/index.js | 4 |
3 files changed, 44 insertions, 1 deletions
diff --git a/docs/README.md b/docs/README.md index 17487c296..5036ea22c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,6 +10,7 @@ Index ### Using the API - [API documentation](Using-the-API/API.md) +- [Streaming API documentation](Using-the-API/Streaming-API.md) - [Testing the API with cURL](Using-the-API/Testing-with-cURL.md) - [OAuth details](Using-the-API/OAuth-details.md) - [Tips for app developers](Using-the-API/Tips-for-app-developers.md) diff --git a/docs/Using-the-API/Streaming-API.md b/docs/Using-the-API/Streaming-API.md new file mode 100644 index 000000000..b6d41ab0e --- /dev/null +++ b/docs/Using-the-API/Streaming-API.md @@ -0,0 +1,40 @@ +Streaming API +============= + +Your application can use a 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. + +### 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/hashtag** + +Returns all public statuses for a particular hashtag (query param `tag`) + +### 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 + +``` + +[See MDN](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) + +### 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| + +The payload is JSON-encoded. diff --git a/streaming/index.js b/streaming/index.js index fd57c4e56..af1da8ae7 100644 --- a/streaming/index.js +++ b/streaming/index.js @@ -90,7 +90,9 @@ const streamFrom = (id, req, res, needsFiltering = false) => { redisClient.on('message', (channel, message) => { const { event, payload } = JSON.parse(message) - if (needsFiltering) { + // Only messages that may require filtering are statuses, since notifications + // are already personalized and deletes do not matter + if (needsFiltering && event === 'update') { pgPool.connect((err, client, done) => { if (err) { log.error(err) |