Start chapter expansion.
@@ -3,7 +3,7 @@ Represents a saved document, i.e. and image with a seal and optionally some stam
|
||||
Will usually be associated with an `Event`, and event documents should generally be queried through the Event routes.
|
||||
However, `Document` also supports CRUD operations separately for storing arbitrary non-event documents.
|
||||
|
||||
|
||||
## Fields
|
||||
| field | type | required | description |
|
||||
| --------------- | --------- | -------- | -------------------------------------------------------------- |
|
||||
| `document_id` | integer | - | UID for this document |
|
||||
@@ -13,6 +13,8 @@ However, `Document` also supports CRUD operations separately for storing arbitra
|
||||
| `metadata` | string? | no | Optional arbitrary associated metadata. |
|
||||
| `stamps` | [`Stamp`] | no | List of stamps attached to this document. |
|
||||
|
||||
## Routes
|
||||
|
||||
- `POST` `/documents`
|
||||
- Create and return a `Document`.
|
||||
- Stamps may be added to the document by passing a list of `Stamp`s in the `stamps` field.
|
||||
@@ -40,4 +42,3 @@ However, `Document` also supports CRUD operations separately for storing arbitra
|
||||
- Returns the deleted `Document`.
|
||||
- `*` `/documents/{document_id}/stamps`
|
||||
- Inherits all `/stamps` routes with `document_id` set.
|
||||
|
||||
|
||||
89
event.md
89
event.md
@@ -3,6 +3,10 @@ An Event represents event data for one of the saved events.
|
||||
This will typically have a `Document` attached with image data saved from the event.
|
||||
Events may also be created without documents, in which case the `document` and `document_id` fields will be `null`.
|
||||
|
||||
There are four types of events ('PlainEvent', 'SubEvent', 'CheerEvent', 'RaidEvent'), identified by their `event_type` field.
|
||||
The API will only ever accept or return these four concrete types, and never the abstract `Event` type. However, the abstraction is useful since multi-value endpoints such as `GET /events` will return a combination of these concrete types, which we shall just refer to as `Event`s.
|
||||
|
||||
## Fields
|
||||
| field | type | required | description |
|
||||
| ------------ | ------- | -------- | --------------------------------------------------------------- |
|
||||
| `event_id` | integer | - | UID for this event |
|
||||
@@ -17,16 +21,56 @@ Events may also be created without documents, in which case the `document` and `
|
||||
|
||||
|
||||
Allowed and possible values for `EventType` are `plain`, `subscriber`, `cheer`, `raid`.
|
||||
The `event_type` *must* be specified when creating an event.
|
||||
The `event_type` *must* be specified when creating an event (you cannot create a base Event, only one of the following four event types).
|
||||
|
||||
### `PlainEvent`
|
||||
An `Event` of type `plain` has the following further fields.
|
||||
|
||||
| field | type | required | description |
|
||||
| ------------ | ------- | -------- | --------------------------------------------------------------- |
|
||||
| `message` | string | yes | Message for this event. |
|
||||
|
||||
|
||||
### `SubEvent`
|
||||
An `Event` of type `subscriber` has the following further fields.
|
||||
|
||||
| field | type | required | description |
|
||||
| ------------ | ------- | -------- | --------------------------------------------------------------- |
|
||||
| `tier` | integer | yes | Tier of the subscription. |
|
||||
| `subscribed_length` | integer | yes | Subscription length (not sure what the unit is?) |
|
||||
| `message` | string? | no | Subscription message. |
|
||||
|
||||
- [ ] What is the unit of `subscribed_length`? Is it cumulative? Does it make any sense to have `subscription_start` for the start of the current subscription?
|
||||
- [ ] `message` was not in the original spec, does it make sense to add?
|
||||
|
||||
### `CheerEvent`
|
||||
An `Event` of type `cheer` has the following further fields.
|
||||
|
||||
| field | type | required | description |
|
||||
| ------------ | ------- | -------- | -------------------------------------- |
|
||||
| `amount` | integer | yes | Number of bits cheered |
|
||||
| `cheer_type` | string? | no | Type of cheer |
|
||||
| `message` | string? | no | Message associated with the bit cheer. |
|
||||
|
||||
- [ ] `type` was not in the original spec, does it make sense? `message` as well.
|
||||
|
||||
|
||||
### `RaidEvent`
|
||||
An `Event` of type `raid` has the following further fields.
|
||||
|
||||
| field | type | required | description |
|
||||
| ------------ | ------- | -------- | --------------------------------------------------------------- |
|
||||
| `viewer_count` | integer | yes | Number of viewers who came with the raid. |
|
||||
|
||||
|
||||
## Routes
|
||||
- `POST` `/events`
|
||||
- Create a return a new `Event`.
|
||||
- The `event_type` *must* be specified, and the additional fields for that event type should be considered.
|
||||
- The `document` *should* be specified in the form of a `Document` (as in `POST /documets`).
|
||||
- The `document` *should* be specified in the form of a `Document` (as in `POST /documents`), however, may be specified as a `document_id` instead to attach to an existing document.
|
||||
- The `user` *may* be specified in the form of a `User` (as in `POST /user`), in which case `user_id` is not required and will be filled from the created `User`.
|
||||
- Supplying both `user_id` and `user` is not supported.
|
||||
- If a `user` already exists with the given `twitch_id`, then that `user` will instead be *updated* with the given fields, and the `user_id` of the existing user will be used to create the `Event`. This behaviour is distinct to the `POST /user` endpoint which will *error* if the user already exists.
|
||||
- If a `user` already exists with the given `twitch_id`, then that `user` will instead be *updated* with the given fields, and the `user_id` of the existing user will be used to create the `Event`. This behaviour is distinct to the `POST /users` endpoint which will *error* if the user already exists.
|
||||
- `GET` `/events`
|
||||
- Returns `events` matching the provided filters.
|
||||
- Intended to be the typical way of retrieving events and documents.
|
||||
@@ -59,42 +103,11 @@ The `event_type` *must* be specified when creating an event.
|
||||
|
||||
- [ ] It might make sense to add the subtype fields for filtering as well
|
||||
|
||||
#### `PlainEvent`
|
||||
An `Event` of type `plain` has the following further fields.
|
||||
|
||||
| field | type | required | description |
|
||||
| ------------ | ------- | -------- | --------------------------------------------------------------- |
|
||||
| `message` | string | yes | Message for this event. |
|
||||
## Examples
|
||||
### Get sub events from a given user
|
||||
|
||||
|
||||
#### `SubEvent`
|
||||
An `Event` of type `subscriber` has the following further fields.
|
||||
|
||||
| field | type | required | description |
|
||||
| ------------ | ------- | -------- | --------------------------------------------------------------- |
|
||||
| `tier` | integer | yes | Tier of the subscription. |
|
||||
| `subscribed_length` | integer | yes | Subscription length (not sure what the unit is?) |
|
||||
| `message` | string? | no | Subscription message. |
|
||||
|
||||
- [ ] What is the unit of `subscribed_length`? Is it cumulative? Does it make any sense to have `subscription_start` for the start of the current subscription?
|
||||
- [ ] `message` was not in the original spec, does it make sense to add?
|
||||
|
||||
#### `CheerEvent`
|
||||
An `Event` of type `cheer` has the following further fields.
|
||||
|
||||
| field | type | required | description |
|
||||
| ------------ | ------- | -------- | -------------------------------------- |
|
||||
| `amount` | integer | yes | Number of bits cheered |
|
||||
| `cheer_type` | string? | no | Type of cheer |
|
||||
| `message` | string? | no | Message associated with the bit cheer. |
|
||||
|
||||
- [ ] `type` was not in the original spec, does it make sense? `message` as well.
|
||||
### Create a message event, then add a stamp
|
||||
|
||||
|
||||
#### `RaidEvent`
|
||||
An `Event` of type `raid` has the following further fields.
|
||||
|
||||
| field | type | required | description |
|
||||
| ------------ | ------- | -------- | --------------------------------------------------------------- |
|
||||
| `viewer_count` | integer | yes | Number of viewers who came with the raid. |
|
||||
|
||||
### Remove stamps from an event document
|
||||
|
||||
Reference in New Issue
Block a user