diff --git a/document.md b/document.md index 57a2bda..2246934 100644 --- a/document.md +++ b/document.md @@ -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. - diff --git a/event.md b/event.md index a32d8fc..baf9646 100644 --- a/event.md +++ b/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