ulith/pronounss
1
0
Fork 0
forked from mirrors/pronouns.cc
Code Pull requests Activity

add snowflake IDs to docs

Browse source
This commit is contained in:
sam 2023-10-13 23:24:39 +02:00
parent cb8cfb9d2f
commit 65b171696a
No known key found for this signature in database
GPG key ID: B4EF20DDE721CAA1
4 changed files with 35 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
docs/api/endpoints/index.md
View file

@ -45,9 +45,10 @@ A user can set custom word preferences, which can have custom icons and tooltips
## Pride flag ## Pride flag
| Field | Type | Description | | Field | Type | Description |
| ----------- | ------- | ------------------------------------- | | ----------- | --------- | ------------------------------------- |
| id | string | the flag's unique ID | | id | string | the flag's unique ID |
| hash | string | the flag's [image hash](/api/#images) | | id_new | snowflake | the flag's unique snowflake ID |
| name | string | the flag's name | | hash | string | the flag's [image hash](/api/#images) |
| description | string? | the flag's description or alt text | | name | string | the flag's name |
| description | string? | the flag's description or alt text |

26
docs/api/endpoints/members.md
View file

@ -5,6 +5,7 @@
| Field | Type | Description | | Field | Type | Description |
| ------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------- | | ------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------- |
| id | string | the member's unique ID | | id | string | the member's unique ID |
| id_new | snowflake | the member's unique snowflake ID |
| sid | string | the member's 6-letter short ID | | sid | string | the member's 6-letter short ID |
| name | string | the member's name | | name | string | the member's name |
| display_name | string? | the member's display name or nickname | | display_name | string? | the member's display name or nickname |
@ -23,6 +24,7 @@
| Field | Type | Description | | Field | Type | Description |
| ------------------ | ---------------------------------------------------- | -------------------------------------- | | ------------------ | ---------------------------------------------------- | -------------------------------------- |
| id | string | the user's unique ID | | id | string | the user's unique ID |
| id_new | snowflake | the user's unique snowflake ID |
| name | string | the user's username | | name | string | the user's username |
| display_name | string? | the user's display name or nickname | | display_name | string? | the user's display name or nickname |
| avatar | string? | the user's [avatar hash](/api/#images) | | avatar | string? | the user's [avatar hash](/api/#images) |
@ -95,18 +97,18 @@ Returns the updated [member](./members#member-object) on success.
#### Request body parameters #### Request body parameters
| Field | Type | Description | | Field | Type | Description |
| ------------------ | -------------------- | --------------------------------------------------------------------------------------------------- | | ------------ | --------------- | ------------------------------------------------------------------------------------------------------ |
| name | string | the member's new name. Must be unique per user, and be between 1 and 100 characters. | | name | string | the member's new name. Must be unique per user, and be between 1 and 100 characters. |
| display_name | string | the member's new display name. Must be between 1 and 100 characters | | display_name | string | the member's new display name. Must be between 1 and 100 characters |
| bio | string | the member's new bio. Must be between 1 and 1000 characters | | bio | string | the member's new bio. Must be between 1 and 1000 characters |
| links | string[] | the member's new profile links. Maximum 25 links, and links must be between 1 and 256 characters | | links | string[] | the member's new profile links. Maximum 25 links, and links must be between 1 and 256 characters |
| names | field_entry[] | the member's new preferred names | | names | field_entry[] | the member's new preferred names |
| pronouns | pronoun_entry[] | the member's new preferred pronouns | | pronouns | pronoun_entry[] | the member's new preferred pronouns |
| fields | field[] | the member's new profile fields | | fields | field[] | the member's new profile fields |
| flags | string[] | the member's new flags. This must be an array of [pride flag](./#pride-flag) IDs. | | flags | string[] | the member's new flags. This must be an array of [pride flag](./#pride-flag) IDs, _not_ snowflake IDs. |
| avatar | string | the member's new avatar. This must be a PNG, JPEG, or WebP image, encoded in base64 data URI format | | avatar | string | the member's new avatar. This must be a PNG, JPEG, or WebP image, encoded in base64 data URI format |
| unlisted | bool | whether or not the member should be hidden from the member list | | unlisted | bool | whether or not the member should be hidden from the member list |
### Delete member ### Delete member

4
docs/api/endpoints/users.md
View file

@ -5,6 +5,7 @@
| Field | Type | Description | | Field | Type | Description |
| ------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------- | | ------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------- |
| id | string | the user's unique ID | | id | string | the user's unique ID |
| id_new | snowflake | the user's unique snowflake ID |
| sid | string | the user's 5 letter short ID | | sid | string | the user's 5 letter short ID |
| name | string | the user's username | | name | string | the user's username |
| display_name | string? | the user's display name or nickname | | display_name | string? | the user's display name or nickname |
@ -45,6 +46,7 @@
| Field | Type | Description | | Field | Type | Description |
| ------------ | ----------------------------------- | ---------------------------------------- | | ------------ | ----------------------------------- | ---------------------------------------- |
| id | string | the member's unique ID | | id | string | the member's unique ID |
| id_new | snowflake | the member's unique snowflake ID |
| sid | string | the member's 6-letter short ID | | sid | string | the member's 6-letter short ID |
| name | string | the member's name | | name | string | the member's name |
| display_name | string? | the member's display name or nickname | | display_name | string? | the member's display name or nickname |
@ -89,7 +91,7 @@ Returns the updated [user](./users#user-object) object on success.
| names | field_entry[] | the user's new preferred names | | names | field_entry[] | the user's new preferred names |
| pronouns | pronoun_entry[] | the user's new preferred pronouns | | pronouns | pronoun_entry[] | the user's new preferred pronouns |
| fields | field[] | the user's new profile fields | | fields | field[] | the user's new profile fields |
| flags | string[] | the user's new flags. This must be an array of [pride flag](./#pride-flag) IDs. | | flags | string[] | the user's new flags. This must be an array of [pride flag](./#pride-flag) IDs, _not_ snowflake IDs. |
| avatar | string | the user's new avatar. This must be a PNG, JPEG, or WebP image, encoded in base64 data URI format | | avatar | string | the user's new avatar. This must be a PNG, JPEG, or WebP image, encoded in base64 data URI format |
| timezone | string | the user's new timezone. Must be in IANA timezone database format | | timezone | string | the user's new timezone. Must be in IANA timezone database format |
| list_private | bool | whether or not the user's member list should be hidden | | list_private | bool | whether or not the user's member list should be hidden |

18
docs/api/index.md
View file

@ -62,19 +62,23 @@ The "type" column in tables is formatted as follows:
## IDs ## IDs
::: info ### Snowflake IDs
pronouns.cc is [planning a transition](https://codeberg.org/pronounscc/pronouns.cc/issues/89)
to [Snowflake IDs](https://en.wikipedia.org/wiki/Snowflake_ID).
The information below pertains to the current ID format.
:::
The API uses [xid](https://github.com/rs/xid) for unique IDs. These are always serialized as strings. For [multiple reasons](https://codeberg.org/pronounscc/pronouns.cc/issues/89),
pronouns.cc is transitioning to using snowflakes for unique IDs. These will become the default in the next API version,
but are already returned as `id_new` in the relevant objects (users, members, and flags).
### xids
[xid](https://github.com/rs/xid) is the previous unique ID format. These are always serialized as strings.
Although xids have timestamp information embedded in them, this is non-trivial to extract. Although xids have timestamp information embedded in them, this is non-trivial to extract.
xids are unique across _all_ resources, they are never shared (for example, a user and a member cannot share the same ID). xids are unique across _all_ resources, they are never shared (for example, a user and a member cannot share the same ID).
### prns.cc IDs
Users and members also have an additional ID type, `sid`. Users and members also have an additional ID type, `sid`.
These are randomly generated 5 or 6 letter strings, and are used for the prns.cc URL shortener. These are randomly generated 5 or 6 letter strings, and are used for the prns.cc URL shortener.
They can be rerolled once per hour. **These can change at any time**, as short IDs can be rerolled once per hour.
## Images ## Images