83 lines
2.2 KiB
Markdown
83 lines
2.2 KiB
Markdown
|
# Streaming API
|
||
|
|
|
||
|
|
Elstat's Streaming API enables clients to receive realtime
|
||
|
|
updates from the server.
|
||
|
|
|
||
|
|
Clients can subscribe just to *certain* channels in the case
|
||
|
|
they don't want to have a lot of overhead, or they can just
|
||
|
|
not use the Streaming API at all. It is optional.
|
||
|
|
|
||
|
|
|
||
|
|
## Common payload format
|
||
|
|
|
||
|
|
Payloads can not exceed 256 bytes in size.
|
||
|
|
Payloads are JSON encoded.
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
{
|
||
|
|
"op": ANY_INTEGER
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
Extra fields are on each OP's description, instead of being in
|
||
|
|
some `d` field (like Discord's Gateway API).
|
||
|
|
|
||
|
|
|
||
|
|
## Error codes
|
||
|
|
|
||
|
|
| Error code | Name |
|
||
|
|
|---:|:---|
|
||
|
|
|4200|`INVALID_PAYLOAD`|
|
||
|
|
|4420|`TOO_MUCH`|
|
||
|
|
|
||
|
|
|
||
|
|
## OP Codes
|
||
|
|
|
||
|
|
| OP Int | OP Name | Sent/Received by client |
|
||
|
|
|--:|:--|:--:|
|
||
|
|
|-1|`UNSUBSCRIBE`|Sent|
|
||
|
|
|0|`SUBSCRIBE`|Sent|
|
||
|
|
|1|`SUBSCRIBED`|Received|
|
||
|
|
|2|`UNSUBSCRIBED`|Received|
|
||
|
|
|3|`DATA`|Received|
|
||
|
|
|
||
|
|
|
||
|
|
## OP Payloads
|
||
|
|
|
||
|
|
- `SUBSCRIBE`
|
||
|
|
- field: `channels` (`list[str]`), array of channels you want to subscribe to.
|
||
|
|
- reply: `SUBSCRIBED` payload.
|
||
|
|
- `UNSUBSCRIBE`
|
||
|
|
- field: `channels` (`list[str]`), array of channels you want to **un**subscribe from.
|
||
|
|
- reply: `UNSUBSCRIBED` payload.
|
||
|
|
- `SUBSCRIBED`
|
||
|
|
- field: `channels` (`list[str]`), array of channels you *succesfully* subscribed to.
|
||
|
|
- `UNSUBSCRIBED`
|
||
|
|
- field: `channels` (`list[str]`), array of channels you *succesfully* **un**subscribed from.
|
||
|
|
- `DATA`
|
||
|
|
- field: `c` (`str`), the channel the data is coming from.
|
||
|
|
- data: `d` (`list[any]`), the data coming in from the channel.
|
||
|
|
- The first element of `d` is an integer, encoding an UNIX timestamp with millisecond precision.
|
||
|
|
- The second element of `d` is described on *`Channel types`*
|
||
|
|
|
||
|
|
|
||
|
|
## Channel names
|
||
|
|
|
||
|
|
Channels are what clients subscribe to receive data about that channel.
|
||
|
|
Channels are specified as `<type>:<name>`
|
||
|
|
|
||
|
|
e.g `status:elixire` and `graph:elixire`
|
||
|
|
|
||
|
|
### Channel types
|
||
|
|
- `status` channel
|
||
|
|
- Returns a boolean, representing the status of the service
|
||
|
|
- `latency` channel
|
||
|
|
- Returns an integer, representing the latency of the service, in *milliseconds*.
|
||
|
|
|
||
|
|
|
||
|
|
## Connection logic
|
||
|
|
|
||
|
|
- Connect a websocket to `/api/streaming`.
|
||
|
|
- Send a `SUBSCRIBE` payload, receive `SUBSCRIBED` back
|
||
|
|
- Listen to `DATA` payloads and update local state as needed.
|