Basic API docs

This commit is contained in:
powermaker450 2024-09-16 12:14:50 -04:00
parent 7b59fc5e4e
commit 9843459d22
4 changed files with 139 additions and 1 deletions

View file

@ -22,4 +22,4 @@ pnpm build
pnpm start 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)

4
docs/API.md Normal file
View file

@ -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)

75
docs/GET.md Normal file
View file

@ -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"
}
}
```
---

59
docs/POST.md Normal file
View file

@ -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 |
---