diff --git a/API-Documentation.md b/API-Documentation.md index f2da659..3f34708 100644 --- a/API-Documentation.md +++ b/API-Documentation.md @@ -1,3 +1,5 @@ +# API Docs + These pages document the backend API and useage. The API functions work via `GET` and `POST` requests, which both return json info about what happened. @@ -8,4 +10,77 @@ The API will return json with the following values: `status`: which indicates if the action succeeded or not, and is either `ok` or `fail`. -`reason`: which provides more info about why an action succeeded or failed, which is mostly useful for debugging. \ No newline at end of file +`reason`: which provides more info about why an action succeeded or failed, which is mostly useful for debugging. + +## Auth API Documentation +### Register & Login: + +`POST /api/register` with JSON body values of: `name`, `pin`, `pronouns`. + +Will return JSON with `status` and `reason`. + +`POST /api/login` with JSON body values of: `name`, `pin`. + +Will return JSON with `status` and `reason`. + +Will set a private cookie named `token` which is used for authentication. + +### Change User Information + +User information such as name, pin, and pronouns, can be changed currently one at a time. + +`POST /api/change` with JSON body values of: `name`, `changed_event`, `new_event`. + +`name` the user's current username. used for authentication. + +`changed_event` which event to change. value can be one of: `Name`, `Pin`, `Pronouns`. + +`new_event` the new value for the changed event. + +User is authenticated via token. + +### Check if User is Still Logged in + +Instead of having to save the pin and re-login every time to check wether they're logged in, you can just check via the token. + +`GET /api/token/` where `` is the current username. + +Will return JSON with `status` and `reason`. + +### Logout + +This API will remove the cookie from the client, as well as invalidating the token serverside. + +`POST /api/logout` with JSON body values of: `name`. + +Will use the current token as authentication. + +Will return JSON with `status` and `reason`. + +### Get Info About A User + +This API will return info about a user on success. + +`GET /api/users/` + +On success returns JSON in format: +``` +status: ok +user: + name: user's name + pronouns: user's pronouns + role: the users role, one of either 'Normal', 'Moderator', or 'Admin' +``` + +eg: + +``` +{ + status: "ok", + user: { + name: "example", + pronouns: "they/them", + role: "Normal", + }, +} +``` \ No newline at end of file