Basic API docs

README.md

@@ -22,4 +22,4 @@ pnpm build
 pnpm start
 ```
 
-To post a review to the server, use [Simple Review Client](https://git.povario.com/powermaker450/simple-review-client)
+To post a review to the server, use [Simple Review Client](https://git.povario.com/powermaker450/simple-review-client), or consult the [API Docs](https://git.povario.com/powermaker450/simple-review-server/src/branch/main/docs/API.md)

docs/API.md

@@ -0,0 +1,4 @@
+# API Docs
+
+### [POST](https://git.povario.com/powermaker450/simple-review-server/src/branch/main/docs/POST.md)
+### [GET](https://git.povario.com/powermaker450/simple-review-server/src/branch/main/docs/GET.md)

docs/GET.md

@@ -0,0 +1,75 @@
+# GET
+
+## `/api/reviews/`
+
+**Response Codes:** `200` \
+**Response Format:** `JSON`
+
+### Example response:
+
+```
+[
+    {
+        "username": "bob",
+        "rating": 4.5,
+        "title": "All fields",
+        "content": "This user review contains all required and allowed fields!",
+        "id": "a1b2c3",
+        "timestamp": "2024-09-12T03a:55:23.830Z"
+    },
+    {
+        "username": "sarah",
+        "rating": 4.5,
+        "title": "Only a title",
+        "content": null,
+        "id": "e1f2g3",
+        "timestamp": "2024-09-12T03a:56:23.830Z"
+    },
+    {
+        "username": "phillip",
+        "rating": 4.5,
+        "title": null,
+        "content": null,
+        "id": "h1i2j3",
+        "timestamp": "2024-09-12T03a:57:23.830Z"
+    }
+]
+```
+
+---
+
+## `/api/reviews/:id`
+
+**Response Codes:** `200`, `404`, `400` \
+**Response Format:** `JSON`
+
+## Example requests and responses:
+
+### Good Request
+`GET /api/reviews/a1b2c3`
+
+**Server Response (`200`):**
+```
+{
+    "username": "bob",
+    "rating": 4.5,
+    "title": "All fields",
+    "content": "This user review contains all required and allowed fields!",
+    "timestamp": "2024-09-12T03a:55:23.830Z"
+}
+```
+
+### Bad Request
+`GET /api/reviews/a`
+
+**Server Response (`400`)**:
+```
+{
+    error: {
+        "type": "requestError",
+        "message": "review id must be 6 characters"
+    }
+}
+```
+
+---

docs/POST.md

@@ -0,0 +1,59 @@
+# POST
+
+## `/api/post`
+
+**Encoding:** `JSON` \
+**Response Codes:** `201`, `400`, `500` \
+**Response Format:** `JSON`
+
+**Schema:**
+| **Field** | **Type** |     **Info**     | **Required** |
+| --------- | -------- | ---------------- | ------------ |
+| username  | string   | 2-30 characters  | `true`       |
+| rating    | number   | from 0.5-5, only .5 increments | `true` |
+| title     | string   | 0-50 characters | `false` |
+| content   | string   | 0-2000 characters | `false` |
+
+## Example Objects (being submitted by a client):
+
+### Good Request
+```
+{
+    "username": "bob",
+    "rating": 4.5,
+    "title": "All fields",
+    "content": "This user review contains all required and allowed fields!"
+}
+```
+
+**Server Response (`200`):**
+```
+{
+    "message": "review was sent"
+}
+```
+
+### Bad Request
+```
+{
+    "username": "hacker",
+    "rating": -3
+}
+```
+**Server Response (`400`):**
+```
+{
+    "error": {
+        "type": "ValidationError",
+        "message": "rating must be a positive number"
+    }
+}
+```
+
+**Additional info:** When submitted, the server will add two more fields to your review and store this info server side:
+| **Field** | **Type** | **Info** |
+| --------- | -------- | -------- |
+| id        | string   | 6 randomly-generated characters |
+| timestamp | string   | ISO timestamp |
+
+---