From f931db2720a47889b798bf7414131733a36b77d9 Mon Sep 17 00:00:00 2001 From: Erin Nova Date: Fri, 23 Jul 2021 10:35:14 -0400 Subject: [PATCH] Improve API docs --- CHANGELOG.md | 5 +++ Cargo.lock | 2 +- Cargo.toml | 2 +- README.md | 119 +++++++++++++++++++++++++++++++++++---------------- src/auth.rs | 2 +- src/user.rs | 1 - 6 files changed, 89 insertions(+), 42 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 411b2f2..ac16f98 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,8 @@ +## 0.6.0 +- Remove deprecated API +- `/api/register` & `/api/login` now use JSON data +- Changing user info now uses Enum (Name, Pin, or Pronouns) + ### 0.5.2 - When changing a username, it now deletes the previous user instead of creating a new one - Database functions should now use some error handling diff --git a/Cargo.lock b/Cargo.lock index 93fff42..2b12326 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -807,7 +807,7 @@ checksum = "d4fd5641d01c8f18a23da7b6fe29298ff4b55afcccdf78973b24cf3175fee32e" [[package]] name = "pogchat" -version = "0.5.2" +version = "0.6.0" dependencies = [ "bincode", "chrono", diff --git a/Cargo.toml b/Cargo.toml index b2ab2bc..f4a21b4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "pogchat" -version = "0.5.2" +version = "0.6.0" authors = ["Erin Nova "] edition = "2018" diff --git a/README.md b/README.md index 2c7b2fb..fcfc2a9 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,95 @@ # Chat Registration System -The basic backend code needed to register & login to a chat system (to be built). -Send it the unhashed username and pin, and it'll store it in the `users.json` file with the pin hashed with SHA1. +A simple chat system for built for maya's livestream. +Provides a simple API for user authentication, and chat functions. +Frontend & backend code stored here. -## API Documentation +## Auth API Documentation -`POST /api/register///` Register the username with the pin provided if it doesn't already exist -Returns status & reason json. +Most API functions will return JSON in the following format: -`GET /api/users/` Check if the user exists -Returns either +`status`: either `ok` if action succeeded, or `fail` otherwise. -`{ - "status": "fail", - "reason": "user not found", -}` +`reason`: More info about why the action failed. -or +### Register & Login: -`{ - "status": "ok", - "user": { - "name": "", - "pronouns": "", +`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", }, -}` +} +``` -`GET /api/token/` Check if the current token matches the user provided +## Chat API Documentation -DEPRECATED `GET /api/users//` Check if the user exists, and if the pin provided matches -Returns status & reason json. +`POST /api/message/send {"name":"username","body":"message body"}` Post a message with JSON body values of: `name` & `body` -`POST /api/users/change {"name":"","pin":"","changed_event":"name/pin/pronouns","new_event":""` Change a users details via a json post. +Will return JSON with `status` and `reason`. -eg. `POST /api/users/change {"name":"example","pin":"10","changed_event":"name","new_event":"test"` to change the user "example"'s name to "test" - -DEPRECATED `POST /api/users/change////` Change a users pin/name -Returns status & reason json. - -`POST /api/logout {"name":""}` to logout a user if the token matches - - -## Chat Documentation - -`POST /api/message/send {"name":"username","body":"message body"}` Post a json message. -Returns status & reason json. - -`GET /api/message/messages.json` Get a json file of all the messages +`GET /api/message/messages.json` Returns a json file of all the messages ## Chat Planning @@ -66,7 +109,7 @@ Whenever user sends a message, client will send message & token and backend will - [x] Use unix timestamp for date - [ ] Create `chat::delete_message()` - [x] Switch to using sled database to store users - - [ ] Error handling + - [x] Error handling - [x] Token generation & storage - [x] Sets cookie - [x] Store token in json @@ -78,7 +121,7 @@ Whenever user sends a message, client will send message & token and backend will - [x] Pronouns - [x] Set pronouns - [x] Change pronouns -- [ ] make changed_event Enum, use token instead of pin +- [x] make changed_event Enum, use token instead of pin - [ ] Some form of plural support? - [ ] User management (banning, etc.) - [x] User roles (admin, mod, etc.) diff --git a/src/auth.rs b/src/auth.rs index 2e40581..798af4c 100644 --- a/src/auth.rs +++ b/src/auth.rs @@ -194,7 +194,7 @@ pub fn login(data: Json, mut cookies: Cookies) -> JsonValue { } // Change info about a user -#[post("/users/change", format = "json", data = "")] +#[post("/change", format = "json", data = "")] pub fn change_info(input: Json, mut cookies: Cookies) -> JsonValue { // read in the users & hash the pin let mut users: Vec = db_read(); diff --git a/src/user.rs b/src/user.rs index 7114ef3..c7fe77c 100644 --- a/src/user.rs +++ b/src/user.rs @@ -71,7 +71,6 @@ pub enum ChangeEventType { #[derive(Deserialize, Debug)] pub struct ChangeEvent { pub name: String, // name of the user - pub pin: String, // user's pin pub changed_event: ChangeEventType, // which event to change pub new_event: String, // the new value for the event }