diff --git a/README.md b/README.md index b6b425f..4174028 100644 --- a/README.md +++ b/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) diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..3f0c3d1 --- /dev/null +++ b/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) diff --git a/docs/GET.md b/docs/GET.md new file mode 100644 index 0000000..24b2ebe --- /dev/null +++ b/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" + } +} +``` + +--- diff --git a/docs/POST.md b/docs/POST.md new file mode 100644 index 0000000..038194a --- /dev/null +++ b/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 | + +---