From c6195218c59b6d2e32bd754de19c3224a2740db1 Mon Sep 17 00:00:00 2001 From: sam Date: Sat, 2 Sep 2023 03:52:38 +0200 Subject: [PATCH] docs: add other endpoints --- docs/.vitepress/config.mts | 1 + docs/api/endpoints/other.md | 46 +++++++++++++++++++++++++++++++++++++ docs/api/endpoints/users.md | 2 +- 3 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 docs/api/endpoints/other.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 9316ce1..47d4ba6 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -33,6 +33,7 @@ export default defineConfig({ { text: "Object reference", link: "/api/endpoints/" }, { text: "Users", link: "/api/endpoints/users" }, { text: "Members", link: "/api/endpoints/members" }, + { text: "Other", link: "/api/endpoints/other" }, ], }, ], diff --git a/docs/api/endpoints/other.md b/docs/api/endpoints/other.md new file mode 100644 index 0000000..f6d51d2 --- /dev/null +++ b/docs/api/endpoints/other.md @@ -0,0 +1,46 @@ +# Other endpoints + +There are some endpoints that are neither user or member related: + +### Get statistics + +#### `GET /meta` + +Get aggregate statistics for pronouns.cc. +Note: a user is considered active if they have updated their profile, created a member, deleted a member, +or updated a member's profile in the given time period. + +#### Response body + +| Field | Type | Description | +| -------------- | ----------------- | ------------------------------------------------------------------------- | +| git_repository | string | link to the project's Git repository | +| git_commit | string | the commit the backend is built from | +| users | user count object | the total number of users | +| members | int | the total number of non-hidden members | +| require_invite | bool | whether invites are required to sign up. _Always `false` for pronouns.cc_ | + +#### User count object + +| Field | Type | Description | +| ------------ | ---- | ------------------------------------------- | +| total | int | total number of users | +| active_month | int | number of users active in the last month | +| active_week | int | number of users active in the last week | +| active_day | int | number of users active in the last 24 hours | + +### Get warnings + +#### `GET /auth/warnings` + +**Requires authentication.** Returns an array of warnings the currently authenticated user has. +Add `?all=true` query parameter to return all warnings, not just unread ones. + +#### Response body + +| Field | Type | Description | +| ---------- | -------- | ---------------------------------------------- | +| id | int | the warning ID | +| reason | string | the reason for the warning | +| created_at | datetime | when the warning was created | +| read | bool | whether the warning has been read/acknowledged | diff --git a/docs/api/endpoints/users.md b/docs/api/endpoints/users.md index 234efa8..961a0b2 100644 --- a/docs/api/endpoints/users.md +++ b/docs/api/endpoints/users.md @@ -68,7 +68,7 @@ If authenticated and the authenticated user is the requested user, also returns #### `GET /users/@me` **Requires authentication.** Gets the currently authenticated [user](./users#user-object), -with all [additional user fields](./users/#additional-user-fields). +with all [additional user fields](./users#additional-user-fields). ### Update current user