diff --git a/DOCS.md b/DOCS.md new file mode 100644 index 0000000..fc69054 --- /dev/null +++ b/DOCS.md @@ -0,0 +1,334 @@ +# Session 3 API Documentation + +This is the API documentation for the AEC 2024 Skill 08 Session 3 API. + +## Preceding Notes + +- A question mark (`?`) in the documentation indicates that the parameter is optional. +- Every endpoint (except for the authentication endpoint) requires the user to be authenticated. +- When a request body contains a file, the request must be sent as `multipart/form-data`. + +## Authentication + +The API uses a simple authentication mechanism. The user must provide a valid username in order to access the API. The username is sent as a JSON object in the request body. The API will respond with a JSON object containing a JSON Web Token (JWT) that must be included in the `Authorization` header of all subsequent requests using the `Bearer` scheme. + +
+ View details + +#### Endpoint + +``` +POST /auth/login +``` + +#### Request Body + +``` +{ + username: string +} +``` + +#### Example Response + +```json +{ + "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEsInVzZXJuYW1lIjoiYmVuamFtaW5fZnJvc3QiLCJpYXQiOjE3MTUwMjY5MjYsImV4cCI6MTcxNzYxODkyNn0.gAm5sI5V2gzIE49_RQAbgBW3zVINHCKd0xaRWT6bwKY" +} +``` + +
+ +## Users + +The API provides endpoints to get a user's profile and their posts. Furthermore, it allows to update the profile of the authenticated user. + +### Get User Profile + +
+ View details + +#### Endpoint + +``` +GET /users/:id +``` + +#### Example Response + +```json +{ + "id": 1, + "createdAt": "2024-05-06T20:22:06.286Z", + "updatedAt": "2024-05-06T20:22:06.286Z", + "username": "benjamin_frost", + "caption": null, + "imageUrl": null, + "posts": [ + { + "id": 1, + "createdAt": "2024-05-06T20:53:30.271Z", + "updatedAt": "2024-05-06T20:53:30.272Z", + "imageUrl": "/uploads/dd229dab-84b2-4000-879e-a38dbb1c8796.jpeg", + "caption": "This is my first post!", + "author": 1, + "stickers": [ + { + "name": "a", + "x": "0.5", + "y": "-0.25", + "rotation": "15" + }, + { + "name": "b", + "x": "0.33", + "y": "0", + "rotation": "0" + } + ], + "location": { + "latitude": 41.40338, + "longitude": 2.17403 + }, + "likedBy": [ + { + "id": 1, + "createdAt": "2024-05-06T20:22:06.286Z", + "updatedAt": "2024-05-06T20:22:06.286Z", + "username": "benjamin_frost", + "caption": null, + "imageUrl": null + } + ], + "comments": [ + { + "id": 1, + "createdAt": "2024-05-06T21:25:22.152Z", + "updatedAt": "2024-05-06T21:25:22.152Z", + "text": "Some comment", + "author": { + "id": 1, + "createdAt": "2024-05-06T20:22:06.286Z", + "updatedAt": "2024-05-06T20:22:06.286Z", + "username": "benjamin_frost", + "caption": null, + "imageUrl": null + }, + "post": 1 + } + ] + } + ] +} +``` + +
+ +### Update User Profile + +
+ View details + +#### Endpoint + +``` +PATCH /users/:id +``` + +#### Request Body + +``` +{ + caption?: string, + image?: File +} +``` + +
+ +## Posts + +The API provides endpoints to get all posts, like a post, unlike a post, comment on a post, and create a new post. + +### Get All Posts + +
+ View details + +#### Endpoint + +``` +GET /posts +``` + +#### Example Response + +```json +[ + { + "id": 1, + "createdAt": "2024-05-06T20:53:30.271Z", + "updatedAt": "2024-05-06T20:53:30.272Z", + "imageUrl": "/uploads/dd229dab-84b2-4000-879e-a38dbb1c8796.jpeg", + "caption": "This is my first post!", + "author": { + "id": 1, + "createdAt": "2024-05-06T20:22:06.286Z", + "updatedAt": "2024-05-06T20:22:06.286Z", + "username": "benjamin_frost", + "caption": null, + "imageUrl": null + }, + "stickers": [ + { + "name": "a", + "x": "0.5", + "y": "-0.25", + "rotation": "15" + }, + { + "name": "b", + "x": "0.33", + "y": "0", + "rotation": "0" + } + ], + "location": { + "latitude": 41.40338, + "longitude": 2.17403 + }, + "likedBy": [ + { + "id": 1, + "createdAt": "2024-05-06T20:22:06.286Z", + "updatedAt": "2024-05-06T20:22:06.286Z", + "username": "benjamin_frost", + "caption": null, + "imageUrl": null + } + ], + "comments": [ + { + "id": 1, + "createdAt": "2024-05-06T21:25:22.152Z", + "updatedAt": "2024-05-06T21:25:22.152Z", + "text": "Some comment", + "author": { + "id": 1, + "createdAt": "2024-05-06T20:22:06.286Z", + "updatedAt": "2024-05-06T20:22:06.286Z", + "username": "benjamin_frost", + "caption": null, + "imageUrl": null + }, + "post": 1 + } + ] + }, + { + "id": 2, + "createdAt": "2024-05-06T20:54:39.213Z", + "updatedAt": "2024-05-06T20:54:39.213Z", + "imageUrl": "/uploads/3037f4d9-a335-434c-b5c3-62cf1d181c64.jpeg", + "caption": "This is my second post!", + "author": { + "id": 1, + "createdAt": "2024-05-06T20:22:06.286Z", + "updatedAt": "2024-05-06T20:22:06.286Z", + "username": "benjamin_frost", + "caption": null, + "imageUrl": null + }, + "stickers": [], + "location": { + "latitude": 41.40338, + "longitude": 2.17403 + }, + "likedBy": [], + "comments": [] + } +] +``` + +
+ +### Like Post + +
+ View details + +#### Endpoint + +``` +POST /posts/:id/likes +``` + +
+ +### Unlike Post + +
+ View details + +#### Endpoint + +``` +DELETE /posts/:id/likes +``` + +
+ +### Comment on Post + +
+ View details + +#### Endpoint + +``` +POST /posts/:id/comments +``` + +#### Request Body + +``` +{ + text: string +} +``` + +
+ +### Create Post + +
+ View details + +#### Endpoint + +``` +POST /posts +``` + +#### Request Body + +``` +{ + caption: string, + image: File, + location: { + latitude: number, + longitude: number + } + stickers?: [ + { + name: string, + x: number, + y: number, + rotation: number + } + ] +} +``` + +