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

docs: add member endpoints

Browse source
This commit is contained in:
sam 2023-09-01 17:02:23 +02:00
parent 50b584c8ea
commit bc1948316c
No known key found for this signature in database
GPG key ID: B4EF20DDE721CAA1
3 changed files with 126 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docs/.vitepress/config.mts
View file

@ -32,6 +32,7 @@ export default defineConfig({
items: [ items: [
{ text: "Object reference", link: "/api/endpoints/" }, { text: "Object reference", link: "/api/endpoints/" },
{ text: "Users", link: "/api/endpoints/users" }, { text: "Users", link: "/api/endpoints/users" },
{ text: "Members", link: "/api/endpoints/members" },
], ],
}, },
], ],

123
docs/api/endpoints/members.md Normal file
View file

@ -0,0 +1,123 @@
# Member endpoints
## Member object
| Field | Type | Description |
| ------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------- |
| id | string | the member's unique 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 |
| bio | string? | the member's description |
| avatar | string? | the member's [avatar hash](/api/#images) |
| links | string[] | the member's profile links |
| names | [field_entry](./#field-entry)[] | the member's preferred names |
| pronouns | [pronoun_entry](./#pronoun-entry)[] | the member's preferred pronouns |
| fields | ?[field](./#field)[] | the member's term fields. Not returned in member list endpoints. |
| flags | [flag](./#pride-flag)[] | the member's pride flags |
| user | partial [user](./members#partial-user-object) object | the user associated with this member |
| unlisted | ?bool | _only returned for your own members_, whether the member is shown in member lists |
## Partial user object
| Field | Type | Description |
| ------------------ | ---------------------------------------------------- | -------------------------------------- |
| id | string | the user's unique 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) |
| custom_preferences | map\[uuid\][custom_preference](./#custom-preference) | the user's custom preferences |
## Endpoints
### Get member
#### `GET /members/{member.id}`
Gets a member by their ID. Returns a [member](./members#member-object) object.
If authenticated and the authenticated user is the owner of the requested member,
also returns the `unlisted` field.
### Get user member
#### `GET /users/{user.id}/members/{member.id} | GET /users/{user.name}/members/{member.name}`
Gets a member by their ID or name. Returns a [member](./members#member-object) object.
If authenticated and the authenticated user is the owner of the requested member,
also returns the `unlisted` field.
### Get user members
#### `GET /users/{user.id}/members | GET /users/{user.name}/members`
Get a user's members. Returns an array of [member](./members#member-object) objects.
### Get current user member
#### `GET /users/@me/members/{member.id} | GET /users/@me/members/{member.name}`
**Requires authentication.** Get one of the currently authenticated user's members by ID or name.
Returns a [member](./members#member-object) object.
### Get current user members
#### `GET /users/@me/members`
**Requires authentication.** Get the currently authenticated user's members.
Returns an array of [member](./members#member-object) objects.
### Create member
#### `POST /members`
**Requires authentication**. Creates a new member.
Returns the newly created [member](./members#member-object) on success.
#### Request body parameters
| Field | Type | Description |
| ------------ | --------------- | --------------------------------------------------------------------------------------------------- |
| name | string | the new member's name. Must be unique per user, and be between 1 and 100 characters. **Required** |
| display_name | string? | the new member's display name. Must be between 1 and 100 characters |
| bio | string? | the new member's bio. Must be between 1 and 1000 characters |
| avatar | string | the new member's avatar. This must be a PNG, JPEG, or WebP image, encoded in base64 data URI format |
| links | string[] | the new member's profile links. Maximum 25 links, and links must be between 1 and 256 characters |
| names | field_entry[] | the new member's preferred names |
| pronouns | pronoun_entry[] | the new member's preferred pronouns |
| fields | field[] | the new member's profile fields |
### Update member
#### `PATCH /members/{member.id}`
**Requires authentication.** Updates the given member.
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 |
### Delete member
#### `DELETE /members/{member.id}`
**Requires authentication.** Deletes the given member. Returns `204 No Content` on success.
### Reroll short ID
#### `GET /members/{member.id}/reroll`
**Requires authentication.** Rerolls the member's short ID.
Returns the updated [member](./members#member-object) on success.
If the user has already rerolled a short ID in the past hour, returns `403 Forbidden`.

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

@ -86,8 +86,8 @@ Returns the updated [user](./users#user-object) object on success.
| bio | string | the user's new bio. Must be between 1 and 1000 characters | | bio | string | the user's new bio. Must be between 1 and 1000 characters |
| member_title | string | the user's new member title. Must be between 1 and 150 characters | | member_title | string | the user's new member title. Must be between 1 and 150 characters |
| links | string[] | the user's new profile links. Maximum 25 links, and links must be between 1 and 256 characters | | links | string[] | the user's new profile links. Maximum 25 links, and links must be between 1 and 256 characters |
| names | field_entry[] | the users's new preferred names | | names | field_entry[] | the user's new preferred names |
| pronouns | pronoun_entry[] | the users'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. |
| 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 |