Tweak some optional fields.

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                          |
+| `cheer_type` | string?  | no       | Type of cheer                          |
-| `message`    | string  | no       | Message associated with the bit 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`
+    - Supports updating `owner_id` and `forgotten_at`
-    - 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.
 - `DELETE` `/specimens/{specimen_id}`
     - Deletes and returns the given `Specimen`
 - `*` `/specimens/{specimen_id}/owner`

api-tasklist.md

@@ -12,50 +12,53 @@
 - [x]  `/documents` 
     - [x]  `POST`
     - [x]  `GET`
-- [ ]  `/documents/{document_id}` 
+- [x]  `/documents/{document_id}` 
-    - [ ]  `GET`
+    - [x]  `GET`
-    - [ ]  `PATCH`
+    - [x]  `PATCH`
-    - [ ]  `DELETE`
+    - [x]  `DELETE`
-- [ ]  `/documents/{document_id}/stamps` which is passed to `/stamps` with `document_id` set.
+- [x]  `/documents/{document_id}/stamps` which is passed to `/stamps` with `document_id` set.
 
-- [ ]  `/events`
+- [x]  `/events`
-    - [ ]  `POST`
+    - [x]  `POST`
-    - [ ]  `GET`
+    - [x]  `GET`
-- [ ]  `/events/{event_id}`
+- [x]  `/events/{event_id}`
-    - [ ]  `GET`
+    - [x]  `GET`
-    - [ ]  `PATCH`
+    - [x]  `PATCH`
-    - [ ]  `DELETE`
+    - [x]  `DELETE`
-- [ ]  `/events/{event_id}/document` which is passed to `/documents/{document_id}`
+- [x]  `/events/{event_id}/document` which is passed to `/documents/{document_id}`
-- [ ]  `/events/{event_id}/user` which is passed to `/users/{user_id}`
+- [x]  `/events/{event_id}/user` which is passed to `/users/{user_id}`
 
-- [ ]  `/users`
+- [x]  `/users`
-    - [ ]  `POST`
+    - [x]  `POST`
-    - [ ]  `GET`
+    - [x]  `GET`
-    - [ ]  `PATCH`
+- [x]  `/users/{user_id}` 
-    - [ ]  `DELETE`
+    - [x]  `GET`
-- [ ]  `/users/{user_id}` 
+    - [x]  `PATCH`
-    - [ ]  `GET`
+    - [x]  `DELETE`
-    - [ ]  `PATCH`
+- [x]  `/users/{user_id}/events` which is passed to `/events`
-    - [ ]  `DELETE`
+- [x]  `/users/{user_id}/specimen` which is passed to `/specimens/{specimen_id}`
-- [ ]  `/users/{user_id}/events` which is passed to `/events`
+- [x]  `/users/{user_id}/specimens` which is passed to `/specimens`
-- [ ]  `/users/{user_id}/specimen` which is passed to `/specimens/{specimen_id}`
+- [x]  `/users/{user_id}/wallet` with `GET`
-- [ ]  `/users/{user_id}/specimens` which is passed to `/specimens`
+- [x]  `/users/{user_id}/transactions` which is passed to `/transactions`
-- [ ]  `/users/{user_id}/wallet` with `GET`
-- [ ]  `/users/{user_id}/transactions` which is passed to `/transactions`
 
-- [ ]  `/specimens` 
+- [x]  `/specimens` 
-    - [ ]  `GET` 
+    - [x]  `GET` 
-    - [ ]  `POST`
+    - [x]  `POST`
-- [ ]  `/specimens/{specimen_id}` 
+- [x]  `/specimens/{specimen_id}` 
-    - [ ]  `PATCH` 
+    - [x]  `GET`
-    - [ ]  `DELETE`
+    - [x]  `PATCH` 
-- [ ]  `/specimens/{specimen_id}/owner` which is passed to `/users/{user_id}`
+    - [x]  `DELETE`
+- [x]  `/specimens/{specimen_id}/owner` which is passed to `/users/{user_id}`
 
-- [ ]  `/transactions` 
+- [x]  `/transactions` 
-    - [ ]  `POST`
+    - [x]  `POST`
-    - [ ]  `GET`
+    - [x]  `GET`
-- [ ]  `/transactions/{transaction_id}`
+- [x]  `/transactions/{transaction_id}`
-    - [ ]  `GET`
+    - [x]  `GET`
-    - [ ]  `PATCH`
+    - [x]  `PATCH`
-    - [ ]  `DELETE`
+    - [x]  `DELETE`
-- [ ]  `/transactions/{transaction_id}/user` which is passed to `/users/{user_id}`
+- [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).