Improve API docs

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

Cargo.lock

@@ -807,7 +807,7 @@ checksum = "d4fd5641d01c8f18a23da7b6fe29298ff4b55afcccdf78973b24cf3175fee32e"
 
 [[package]]
 name = "pogchat"
-version = "0.5.2"
+version = "0.6.0"
 dependencies = [
  "bincode",
  "chrono",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pogchat"
-version = "0.5.2"
+version = "0.6.0"
 authors = ["Erin Nova <erin@the-system.eu.org>"]
 edition = "2018"
 

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/<name>/<pin>/<pronouns>` 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/<name>` 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": "<name>",
-		"pronouns": "<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/<name>` where `<name>` 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/<name>`
+
+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/<name>` Check if the current token matches the user provided
+## Chat API Documentation
 
-DEPRECATED `GET /api/users/<name>/<pin>` 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":"<username>","pin":"<pin>","changed_event":"name/pin/pronouns","new_event":"<new name/pin/pronouns>"` 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/<name>/<pin>/<new-name>/<new-pin>` Change a users pin/name
-Returns status & reason json.
-
-`POST /api/logout {"name":"<username>"}` 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.)

src/auth.rs

@@ -194,7 +194,7 @@ pub fn login(data: Json<LoginEvent>, mut cookies: Cookies) -> JsonValue {
 }
 
 // Change info about a user
-#[post("/users/change", format = "json", data = "<input>")]
+#[post("/change", format = "json", data = "<input>")]
 pub fn change_info(input: Json<ChangeEvent>, mut cookies: Cookies) -> JsonValue {
     // read in the users & hash the pin
     let mut users: Vec<User> = db_read();

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
 }