diff --git a/api-reference.md b/api-reference.md index 05298ae..a04e1ee 100644 --- a/api-reference.md +++ b/api-reference.md @@ -89,11 +89,11 @@ Events may also be created without documents, in which case the `document` and ` | `user` | `User` | no | `User` which triggered this event. | | `user_name` | string? | yes | Name of the user when they triggered this event. | | `occurred_at` | timestamp | yes | When this event originally occurred. Will typically be earlier than `created_at` | -| `created_at` | timestamp | no | When this event was created. Automatically set on creation. | +| `created_at` | timestamp | - | When this event was created. Automatically set on creation. | | `event_type` | string in `EventType` | yes | Type of the event. Must be one of the event types. | -Allowed and possible values for `EventType` are `plain`, `subscriber`, `bit`, `raid`. +Allowed and possible values for `EventType` are `plain`, `subscriber`, `cheer`, `raid`. The `event_type` *must* be specified when creating an event. @@ -126,6 +126,7 @@ The `event_type` *must* be specified when creating an event. - Does not support updating any of the base event fields. - `DELETE` `/events/{event_id}` - Delete and return the given `Event` + - Note this will *also* delete the associated `Document`. - `*` `/events/{event_id}/document` - If the action is `POST`, will *create* and return a `Document` for this event. - Otherwise inherits the `/documents/{document_id}` route with the associated `document_id`. @@ -150,7 +151,7 @@ An `Event` of type `subscriber` has the following further fields. | ------------ | ------- | -------- | --------------------------------------------------------------- | | `tier` | integer | yes | Tier of the subscription. | | `subscribed_length` | integer | yes | Subscription length (not sure what the unit is?) | -| `message` | string | no | Subscription message. | +| `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? @@ -161,8 +162,8 @@ 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. | +| `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. @@ -184,7 +185,8 @@ Represents a twitch user. | `user_id` | integer | - | Internal UID of this user. (NOT the twitch userid) | | `twitch_id` | string? | yes | Twitch user-id for this user. Stored as a string. | | `name` | string? | yes | Twitch name for this user. May not be up to date. | -| `created_at` | timestamp | no | When this user was created (internally). Automatically set on creation. | +| `created_at` | timestamp | - | When this user was created (internally). Automatically set on creation. | +| `preferences` | string? | no | Arbitrary preference string, not used or read. | // The name is stored mainly for easy visual reference/convenience when debugging, and should not be relied on. @@ -213,7 +215,8 @@ Note that the `twitch_id` and `name` parameters are best-effort and there are so - Get the `UserDetails` for the given user. - `PATCH` `/users/{user_id}` - Updates the given `User` - - Supports updating `twitch_id` and `name` + - Supports updating `name` and `preferences`. + - Intended to be extended to update other preference fields in future. - Returns the updated `User` - `DELETE` `/users/{user_id}` - Deletes the given user, and all associated data. This includes: @@ -271,7 +274,7 @@ Represents a specimen, remembered or forgotten. - Create and return a new `Specimen` . - The `owner` *may* be specified in place of the `owner_id`. In this case it should be in the form of a `User` (as in `POST /user`). - Supplying both an `owner_id` and `owner` 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 as the `owner_id` of the created `Specimen`. + - If an `owner` object is supplied and 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 as the `owner_id` of the created `Specimen`. - `GET` `/specimens` - Returns `Specimen`s matching the provided filters. - Supported filter parameters: @@ -282,11 +285,11 @@ Represents a specimen, remembered or forgotten. - `forgotten` - boolean, filters by whether `forgotten_at` is set. - `forgotten_after` - `forgotten_before` +- `GET` `/specimens/{specimen_id}` + - Get the `Specimen` with the given id. - `PATCH` `/specimens/{specimen_id}` - Updates the given `Specimen` - - Supports updating `owner_id` - - I'm not sure why you would want to do this, but there you go - - This route is intended for future updates where `Specimen` has more metadata. + - Supports updating `owner_id` and `forgotten_at` - `DELETE` `/specimens/{specimen_id}` - Deletes and returns the given `Specimen` - `*` `/specimens/{specimen_id}/owner` diff --git a/api-tasklist.md b/api-tasklist.md index ac7f2f5..3fdec4b 100644 --- a/api-tasklist.md +++ b/api-tasklist.md @@ -12,50 +12,53 @@ - [x] `/documents` - [x] `POST` - [x] `GET` -- [ ] `/documents/{document_id}` - - [ ] `GET` - - [ ] `PATCH` - - [ ] `DELETE` -- [ ] `/documents/{document_id}/stamps` which is passed to `/stamps` with `document_id` set. +- [x] `/documents/{document_id}` + - [x] `GET` + - [x] `PATCH` + - [x] `DELETE` +- [x] `/documents/{document_id}/stamps` which is passed to `/stamps` with `document_id` set. -- [ ] `/events` - - [ ] `POST` - - [ ] `GET` -- [ ] `/events/{event_id}` - - [ ] `GET` - - [ ] `PATCH` - - [ ] `DELETE` -- [ ] `/events/{event_id}/document` which is passed to `/documents/{document_id}` -- [ ] `/events/{event_id}/user` which is passed to `/users/{user_id}` +- [x] `/events` + - [x] `POST` + - [x] `GET` +- [x] `/events/{event_id}` + - [x] `GET` + - [x] `PATCH` + - [x] `DELETE` +- [x] `/events/{event_id}/document` which is passed to `/documents/{document_id}` +- [x] `/events/{event_id}/user` which is passed to `/users/{user_id}` -- [ ] `/users` - - [ ] `POST` - - [ ] `GET` - - [ ] `PATCH` - - [ ] `DELETE` -- [ ] `/users/{user_id}` - - [ ] `GET` - - [ ] `PATCH` - - [ ] `DELETE` -- [ ] `/users/{user_id}/events` which is passed to `/events` -- [ ] `/users/{user_id}/specimen` which is passed to `/specimens/{specimen_id}` -- [ ] `/users/{user_id}/specimens` which is passed to `/specimens` -- [ ] `/users/{user_id}/wallet` with `GET` -- [ ] `/users/{user_id}/transactions` which is passed to `/transactions` +- [x] `/users` + - [x] `POST` + - [x] `GET` +- [x] `/users/{user_id}` + - [x] `GET` + - [x] `PATCH` + - [x] `DELETE` +- [x] `/users/{user_id}/events` which is passed to `/events` +- [x] `/users/{user_id}/specimen` which is passed to `/specimens/{specimen_id}` +- [x] `/users/{user_id}/specimens` which is passed to `/specimens` +- [x] `/users/{user_id}/wallet` with `GET` +- [x] `/users/{user_id}/transactions` which is passed to `/transactions` -- [ ] `/specimens` - - [ ] `GET` - - [ ] `POST` -- [ ] `/specimens/{specimen_id}` - - [ ] `PATCH` - - [ ] `DELETE` -- [ ] `/specimens/{specimen_id}/owner` which is passed to `/users/{user_id}` +- [x] `/specimens` + - [x] `GET` + - [x] `POST` +- [x] `/specimens/{specimen_id}` + - [x] `GET` + - [x] `PATCH` + - [x] `DELETE` +- [x] `/specimens/{specimen_id}/owner` which is passed to `/users/{user_id}` -- [ ] `/transactions` - - [ ] `POST` - - [ ] `GET` -- [ ] `/transactions/{transaction_id}` - - [ ] `GET` - - [ ] `PATCH` - - [ ] `DELETE` -- [ ] `/transactions/{transaction_id}/user` which is passed to `/users/{user_id}` +- [x] `/transactions` + - [x] `POST` + - [x] `GET` +- [x] `/transactions/{transaction_id}` + - [x] `GET` + - [x] `PATCH` + - [x] `DELETE` +- [x] `/transactions/{transaction_id}/user` which is passed to `/users/{user_id}` + +# Notes +- Consider making `metadata` a JSONB column for storage of arbitrary metadata which can be updated over API. +- Consider suggesting storage of image name and type in the metadata column (for guidance on how to decode the image).