Dreamspace/adventures
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

(user): Add some subtleties about User fields.

Interitio
2025-06-06 00:06:12 +10:00
parent 763ced9d5d
commit 016d6351da
1 changed files with 13 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
api-reference.md

@@ -82,7 +82,7 @@ Events may also be created without documents, in which case the `document` and `
| `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. |
| `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. |
@@ -177,12 +177,22 @@ 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. |
| `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.
Note that the `twitch_id` and `name` parameters are best-effort and there are some rare cases where they are unreliable:
- If a user linked their twitch account to Discord, and then unlinked the twitch account or deleted it, then `twitch_id` and `name` may be `null`.
- If a user linked *multiple* twitch accounts, then the returned `twitch_id` and `name` will only be for one account.
- In this rare case, filter parameters will still fetch the correct user. This may lead to technically unexpected behaviour, for example:
- Assume a user with `user_id` `10` has linked twitch account `1` and later twitch account `2`.
- Then both `GET /users?twitch_id=2` and `GET /users?twitch_id=1` will return `{"user_id": 10, "twitch_id": 1}`.
- Due to the general ephemeral nature of names, it is not recommended to rely on the `name` field in any way. It is included mainly for ease of debugging and reference.
- [ ] Currently there is no way of retrieving *all* the twitch accounts associated to a user. Is this needed?
- `POST` `/users`
- Create and return a `User`