Add initial reference sheet.
This commit is contained in:
325
reference.md
Normal file
325
reference.md
Normal file
@@ -0,0 +1,325 @@
|
|||||||
|
## Models
|
||||||
|
|
||||||
|
|
||||||
|
### `Stamp`
|
||||||
|
Represents a document stamp.
|
||||||
|
|
||||||
|
| field | type | required | description |
|
||||||
|
| ------------- | ------- | -------- | --------------------------------------------------------------- |
|
||||||
|
| `stamp_id` | integer | - | UID for this stamp (unique amongst all stamps on all documents) |
|
||||||
|
| `document_id` | integer | yes | UID for the `Document` that this stamp belongs to. |
|
||||||
|
| `stamp_type` | string | yes | Stamp type, can be any string |
|
||||||
|
| `pos_x` | integer | yes | x coordinate |
|
||||||
|
| `pos_y` | integer | yes | y coordinate |
|
||||||
|
| `rotation` | float | yes | Rotation in radians |
|
||||||
|
|
||||||
|
- `POST` `/stamps`
|
||||||
|
- Create and return a `Stamp`.
|
||||||
|
- Should generally not be used directly. Instead, create the `Stamp` with the `Document` or with `POST /documents/{document_id}/stamps`
|
||||||
|
- `PUT` `/stamps`
|
||||||
|
- Create and return a list of `Stamp`s.
|
||||||
|
- Should generally not be used directly. Instead, create the `Stamps` with the `Document` or with `PUT /documents/{document_id}/stamps`
|
||||||
|
- `GET` `/stamps/{stamp_id}`
|
||||||
|
- Returns a `Stamp` with the given `stamp_id`, or raises `Not Found` if no stamp exists.
|
||||||
|
- `PATCH` `/stamps/{stamp_id}`
|
||||||
|
- Updates the given `Stamp`.
|
||||||
|
- Supports any settable field.
|
||||||
|
- `DELETE` `/stamps/{stamp_id}`
|
||||||
|
- Delete the specified `Stamp`.
|
||||||
|
|
||||||
|
|
||||||
|
### `Document`
|
||||||
|
Represents a saved document, i.e. and image with a seal and optionally some stamps.
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
| field | type | required | description |
|
||||||
|
| --------------- | --------- | -------- | -------------------------------------------------------------- |
|
||||||
|
| `document_id` | integer | - | UID for this document |
|
||||||
|
| `document_data` | file | yes | Image data (not sure about the encoding yet) |
|
||||||
|
| `seal` | integer | yes | Seal integer |
|
||||||
|
| `created_at` | timestamp | no | When this document was created. Automatically set on creation. |
|
||||||
|
| `metadata` | string? | no | Optional arbitrary associated metadata. |
|
||||||
|
| `stamps` | [`Stamp`] | no | List of stamps attached to this document. |
|
||||||
|
|
||||||
|
- `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.
|
||||||
|
- `GET` `/documents`
|
||||||
|
- Get all `Document`s matching the given parameters. If no parameters are given, returns all documents.
|
||||||
|
- Supported filter parameters:
|
||||||
|
- `document_id`
|
||||||
|
- `seal`
|
||||||
|
- `created_before`
|
||||||
|
- `created_after`
|
||||||
|
- `metadata`
|
||||||
|
- `stamp_type` - Filter documents by whether they have the given stamp type.
|
||||||
|
- `GET` `/documents/{document_id}`
|
||||||
|
- Returns a `Document` with the given `document_id`.
|
||||||
|
- `PATCH` `/documents/{document_id}`
|
||||||
|
- Updates the given `Document`.
|
||||||
|
- Supports updating `document_data`, `seal`, `metadata`.
|
||||||
|
- To update the stamps, use `/documents/{document_id}/stamps`
|
||||||
|
- Returns the updated `Document`.
|
||||||
|
- `DELETE` `/documents/{document_id}`
|
||||||
|
- Delete the given document, and all associated `Stamp`s.
|
||||||
|
- Does not delete the associated `Event` if one exists.
|
||||||
|
- Returns the deleted `Document`.
|
||||||
|
- `*` `/documents/{document_id}/stamps`
|
||||||
|
- Inherits all `/stamps` routes with `document_id` set.
|
||||||
|
|
||||||
|
### `Event`
|
||||||
|
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`.
|
||||||
|
|
||||||
|
| field | type | required | description |
|
||||||
|
| ------------ | ------- | -------- | --------------------------------------------------------------- |
|
||||||
|
| `event_id` | integer | - | UID for this event |
|
||||||
|
| `document_id` | integer? | - | UID of the associated document, if it exists. |
|
||||||
|
| `document` | `Document`? | no | Associated `Document`, if it exists. |
|
||||||
|
| `user_id` | integer | yes | (Internal) UID of the user which triggered this event. |
|
||||||
|
| `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. |
|
||||||
|
| `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`.
|
||||||
|
The `event_type` *must* be specified when creating an event.
|
||||||
|
|
||||||
|
|
||||||
|
- `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 `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.
|
||||||
|
- `GET` `/events`
|
||||||
|
- Returns `events` matching the provided filters.
|
||||||
|
- Intended to be the typical way of retrieving events and documents.
|
||||||
|
- Supported filter parameters:
|
||||||
|
- `event_id`
|
||||||
|
- `document_id`
|
||||||
|
- `document_seal` - Filter by document seal
|
||||||
|
- `user_id`
|
||||||
|
- `user_name`
|
||||||
|
- `occurred_before`
|
||||||
|
- `occurred_after`
|
||||||
|
- `created_before`
|
||||||
|
- `created_after`
|
||||||
|
- `event_type`
|
||||||
|
- `GET` `/events/{event_id}`
|
||||||
|
- Returns an `Event` with the given `event_id`.
|
||||||
|
- `PATCH` `/events/{event_id}`
|
||||||
|
- Updates and returns the given `Event`.
|
||||||
|
- Supports updating all added fields in the relevant event type.
|
||||||
|
- Does not support updating any of the base event fields.
|
||||||
|
- `DELETE` `/events/{event_id}`
|
||||||
|
- Delete and return the given `Event`
|
||||||
|
- `*` `/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`.
|
||||||
|
- If there is no `document` associated, will raise `Not Found`.
|
||||||
|
- `*` `/events/{event_id}/user`
|
||||||
|
- Inherits the `/users/{user_id}` route with the associated `user_id`.
|
||||||
|
|
||||||
|
- [ ] 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. |
|
||||||
|
|
||||||
|
|
||||||
|
#### `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. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `User`
|
||||||
|
Represents a twitch user.
|
||||||
|
|
||||||
|
| field | type | required | description |
|
||||||
|
| ------------ | --------- | -------- | ----------------------------------------------------------------------- |
|
||||||
|
| `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. |
|
||||||
|
|
||||||
|
// The name is stored mainly for easy visual reference/convenience when debugging, and should not be relied on.
|
||||||
|
|
||||||
|
|
||||||
|
- `POST` `/users`
|
||||||
|
- Create and return a `User`
|
||||||
|
- `GET` `/users`
|
||||||
|
- Get all `User`s matching the given parameters
|
||||||
|
- Supported filter parameters:
|
||||||
|
- `user_id`
|
||||||
|
- `twitch_id`
|
||||||
|
- `name` - Supported, but should not typically be used.
|
||||||
|
- `created_after`
|
||||||
|
- `created_before`
|
||||||
|
- `GET` `/users/{user_id}`
|
||||||
|
- Get the `UserDetails` for the given user.
|
||||||
|
- `PATCH` `/users/{user_id}`
|
||||||
|
- Updates the given `User`
|
||||||
|
- Supports updating `twitch_id` and `name`
|
||||||
|
- Returns the updated `User`
|
||||||
|
- `DELETE` `/users/{user_id}`
|
||||||
|
- Deletes the given user, and all associated data. This includes:
|
||||||
|
- All `Event`s associated to the user (cascading as in `DELETE /events/{event_id}`)
|
||||||
|
- All `Specimen`s associated to the user.
|
||||||
|
- All `InventoryItem`s owned by the user.
|
||||||
|
- All `Transaction`s made by the user.
|
||||||
|
- Returns `UserDetails` of the deleted user.
|
||||||
|
- `*` `/users/{user_id}/events`
|
||||||
|
- Inherits all `/events` routes with `user_id` set.
|
||||||
|
- `*` `/users/{user_id}/specimen`
|
||||||
|
- If the action is `POST`, will *create* and return a `Specimen` for this user.
|
||||||
|
- Note that this will error if the user already has an active specimen.
|
||||||
|
- Otherwise inherits the `/specimens/{specimen_id}` with `specimen_id` set to the user's active specimen.
|
||||||
|
- If the user does not have an active `Specimen` this will raise `NotFound`.
|
||||||
|
- `*` `/user/{user_id}/specimens`
|
||||||
|
- Inherits all `/specimens` routes with the `owner_id` set to `user_id`.
|
||||||
|
- `GET` `/users/{user_id}/wallet`
|
||||||
|
- Will return the current amount in the user's wallet.
|
||||||
|
- Not typically used and only included for route consistency.
|
||||||
|
- `*` `/users/{user_id}/transactions`
|
||||||
|
- Inherits all routes from the `/transactions` route, with `user_id` set.
|
||||||
|
|
||||||
|
|
||||||
|
### `UserDetails`
|
||||||
|
This is a convenience model presenting the current natural 'state' of the user,
|
||||||
|
including their current `Specimen`, their wallet, and their current inventory.
|
||||||
|
|
||||||
|
This is the model returned by `GET /users`.
|
||||||
|
Note that the `specimen`, `inventory`, and `wallet` fields cannot be set or updated directly,
|
||||||
|
instead use `/users/{user_id}/specimen`, `/users/{user_id}/inventory`, and `/users/{user_id}/transactions` respectively.
|
||||||
|
The wallet is viewable from `/users/{user_id}/wallet`, but does not support direct updates.
|
||||||
|
(All updates must occur through transactions.)
|
||||||
|
|
||||||
|
In *addition* to the fields from `User`, this model has the following fields
|
||||||
|
|
||||||
|
| field | type | required | description |
|
||||||
|
| ------------ | ------- | -------- | --------------------------------------------------------------- |
|
||||||
|
| `specimen` | `Specimen`? | - | Current living specimen for this user if it exists. |
|
||||||
|
| `inventory` | [`InventoryItem`] | - | List of active inventory items for this user. |
|
||||||
|
| `wallet` | integer | - | How much currency the user currently has. |
|
||||||
|
|
||||||
|
### `Specimen`
|
||||||
|
Represents a specimen, remembered or forgotten.
|
||||||
|
|
||||||
|
| field | type | required | description |
|
||||||
|
| -------------- | ---------- | -------- | -------------------------------------------------------------------------- |
|
||||||
|
| `specimen_id` | integer | - | UID of this specimen |
|
||||||
|
| `owner_id` | integer | yes | (Internal) id of the user who owns this specimen |
|
||||||
|
| `owner` | `User` | no | User who owns this specimen |
|
||||||
|
| `born_at` | timestamp | no | When this specimen came into existence. Will be set to `now` if not given. |
|
||||||
|
| `forgotten_at` | timestamp? | no | When this specimen was forgotten. |
|
||||||
|
|
||||||
|
- `POST` `/specimens`
|
||||||
|
- 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`.
|
||||||
|
- `GET` `/specimens`
|
||||||
|
- Returns `Specimen`s matching the provided filters.
|
||||||
|
- Supported filter parameters:
|
||||||
|
- `specimen_id`
|
||||||
|
- `owner_id`
|
||||||
|
- `born_after`
|
||||||
|
- `born_before`
|
||||||
|
- `forgotten` - boolean, filters by whether `forgotten_at` is set.
|
||||||
|
- `forgotten_after`
|
||||||
|
- `forgotten_before`
|
||||||
|
- `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.
|
||||||
|
- `DELETE` `/specimens/{specimen_id}`
|
||||||
|
- Deletes and returns the given `Specimen`
|
||||||
|
- `*` `/specimens/{specimen_id}/owner`
|
||||||
|
- Inherits all routes from the `/users/{user_id}` route with the associated `owner_id`.
|
||||||
|
|
||||||
|
// Notably, the inheritance allows a lot of cyclic references. You can for example do `GET /events/1/user/specimen/owner/specimen/user/...` and obtain the expected response. Each level adds the relevant filter parameter or overwrites it if the parameter is already set.
|
||||||
|
|
||||||
|
### `InventoryItem`
|
||||||
|
// TODO
|
||||||
|
// Leaving this for now since I'm not sure how inventories should actually work.
|
||||||
|
// There are a few different models with significant differences.
|
||||||
|
// For example, are there any persistent items which don't need to be owned by a user? i.e. the item can be removed from a user's inventory but still exists and is now possibly useable by another user? Or are all items ephemeral and obtainable in certain quantities by users? Are items purchasable? Are there 'unique' items which can only exist once? Can users trade items or given them to the specimen (req specimen inventory).. etc.
|
||||||
|
// So leaving this for now until there is a better idea of what items and inventories are since the model would probably need a rework anyway
|
||||||
|
|
||||||
|
### `Transaction`
|
||||||
|
Represents a monetary transaction for a particular user.
|
||||||
|
|
||||||
|
| field | type | required | description |
|
||||||
|
| ---------------- | --------- | -------- | ----------------------------------------------------------------------------- |
|
||||||
|
| `transaction_id` | integer | - | UID for this transaction |
|
||||||
|
| `user_id` | integer | yes | (Internal) id of the user making the transaction. |
|
||||||
|
| `user` | `User` | - | User making the transaction. |
|
||||||
|
| `amount` | integer | yes | Amount of currency *added* to the user's account. May be negative. |
|
||||||
|
| `description` | string | yes | Description of this transaction. |
|
||||||
|
| `reference` | string? | no | Optional reference string. |
|
||||||
|
| `created_at` | timestamp | - | Timestamp at which this transaction was performed. Cannot be set or modified. |
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
- `POST` `/transactions`
|
||||||
|
- Create and return a new `Transaction`.
|
||||||
|
- Note that *unlike* other models containing a `User`, creation of a new `User` with a `Transaction` is not supported. Ensure the user exists before creating the transaction.
|
||||||
|
- `GET` `/transactions`
|
||||||
|
- Get all `Transactions` matching the given parameters.
|
||||||
|
- Supported filter parameters:
|
||||||
|
- `transaction_id`
|
||||||
|
- `user_id`
|
||||||
|
- `amount`
|
||||||
|
- `description`
|
||||||
|
- `reference`
|
||||||
|
- `created_before`
|
||||||
|
- `created_after`
|
||||||
|
- `GET` `/transactions/{transaction_id}`
|
||||||
|
- Get the `Transaction` for the given `transaction_id`
|
||||||
|
- `PATCH` `/transactions/{transaction_id}`
|
||||||
|
- Not supported, `Transactions` are considered immutable.
|
||||||
|
- `DELETE` `/transactions/{transaction_id}`
|
||||||
|
- Not supported. `Transactions` cannot be individually deleted.
|
||||||
|
- Note that if the `User` is deleted then the all their `Transactions` will also be deleted.
|
||||||
|
- To reset or set a User's balance, submit a `Transaction` which changes it to the desired value.
|
||||||
|
- `*` `/transactions/{transaction_id}/user`
|
||||||
|
- Inherits all routes from `/users/{user_id}` with the associated `user_id`.
|
||||||
Reference in New Issue
Block a user