From 65b171696a2c0fd838f209da6c6da084e08685f0 Mon Sep 17 00:00:00 2001 From: sam Date: Fri, 13 Oct 2023 23:24:39 +0200 Subject: [PATCH] add snowflake IDs to docs --- docs/api/endpoints/index.md | 13 +++++++------ docs/api/endpoints/members.md | 26 ++++++++++++++------------ docs/api/endpoints/users.md | 4 +++- docs/api/index.md | 18 +++++++++++------- 4 files changed, 35 insertions(+), 26 deletions(-) diff --git a/docs/api/endpoints/index.md b/docs/api/endpoints/index.md index 0b14002..556f1c9 100644 --- a/docs/api/endpoints/index.md +++ b/docs/api/endpoints/index.md @@ -45,9 +45,10 @@ A user can set custom word preferences, which can have custom icons and tooltips ## Pride flag -| Field | Type | Description | -| ----------- | ------- | ------------------------------------- | -| id | string | the flag's unique ID | -| hash | string | the flag's [image hash](/api/#images) | -| name | string | the flag's name | -| description | string? | the flag's description or alt text | +| Field | Type | Description | +| ----------- | --------- | ------------------------------------- | +| id | string | the flag's unique ID | +| id_new | snowflake | the flag's unique snowflake ID | +| hash | string | the flag's [image hash](/api/#images) | +| name | string | the flag's name | +| description | string? | the flag's description or alt text | diff --git a/docs/api/endpoints/members.md b/docs/api/endpoints/members.md index 2a41a4c..fb1438d 100644 --- a/docs/api/endpoints/members.md +++ b/docs/api/endpoints/members.md @@ -5,6 +5,7 @@ | Field | Type | Description | | ------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------- | | 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 | | name | string | the member's name | | display_name | string? | the member's display name or nickname | @@ -23,6 +24,7 @@ | Field | Type | Description | | ------------------ | ---------------------------------------------------- | -------------------------------------- | | id | string | the user's unique ID | +| id_new | snowflake | the user's unique snowflake ID | | name | string | the user's username | | display_name | string? | the user's display name or nickname | | 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 -| Field | Type | Description | -| ------------------ | -------------------- | --------------------------------------------------------------------------------------------------- | -| 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 | -| 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 | -| names | field_entry[] | the member's new preferred names | -| pronouns | pronoun_entry[] | the member's new preferred pronouns | -| 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. | -| 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 | +| Field | Type | Description | +| ------------ | --------------- | ------------------------------------------------------------------------------------------------------ | +| 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 | +| 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 | +| names | field_entry[] | the member's new preferred names | +| pronouns | pronoun_entry[] | the member's new preferred pronouns | +| 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, _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 | +| unlisted | bool | whether or not the member should be hidden from the member list | ### Delete member diff --git a/docs/api/endpoints/users.md b/docs/api/endpoints/users.md index 961a0b2..b671f3a 100644 --- a/docs/api/endpoints/users.md +++ b/docs/api/endpoints/users.md @@ -5,6 +5,7 @@ | Field | Type | Description | | ------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------- | | 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 | | name | string | the user's username | | display_name | string? | the user's display name or nickname | @@ -45,6 +46,7 @@ | Field | Type | Description | | ------------ | ----------------------------------- | ---------------------------------------- | | 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 | | name | string | the member's name | | 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 | | pronouns | pronoun_entry[] | the user's new preferred pronouns | | 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 | | 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 | diff --git a/docs/api/index.md b/docs/api/index.md index 0db8486..51b9eec 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -62,19 +62,23 @@ The "type" column in tables is formatted as follows: ## IDs -::: info -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. -::: +### Snowflake IDs -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. 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`. 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