Generated API Docs using AI, Might edit later if there is an issue or it's hard to read. Finished API Functions

This commit is contained in:
Esad Mustafoski
2025-03-17 21:39:26 +01:00
parent 8b992017ba
commit 497d5aa28f
8 changed files with 749 additions and 49 deletions

View File

@@ -0,0 +1,499 @@
# This was generated using AI!!! Will edit if errors are found.
# API Documentation
## Index
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/` | Returns basic information and directions for using the API endpoints. |
| GET | `/api` | Redirects to the full API documentation. |
---
## Account Endpoints
| Method | Endpoint | Description |
|--------|-------------------------------------------|----------------------------------------------------------------|
| POST | `/api/account/login` | Logs in a user with username and password. |
| POST | `/api/account/register` | Registers a new user with required details. |
| POST | `/api/account/logout` | Logs a user out. (TODO) |
| POST | `/api/account/password/forgot` | Initiates password recovery. (TODO) |
| POST | `/api/account/password/reset` | Resets the password. (TODO) |
| POST | `/api/account/password/change` | Changes the password. (TODO) |
| POST | `/api/account/email/change-email` | Changes the user's email address. (TODO) |
| POST | `/api/account/email/verify-email` | Verifies a user's email. (TODO) |
| POST | `/api/account/delete-account` | Deletes the user account. (TODO) |
| POST | `/api/account/block` | Blocks a user account. (TODO) |
---
## Auth Endpoints
| Method | Endpoint | Description |
|--------|----------------------|--------------------------------------------------|
| GET | `/api/auth` | Auth endpoint (placeholder). |
| GET | `/api/auth/verify` | Verifies an authentication token. (TODO) |
| GET | `/api/auth/refresh` | Refreshes an authentication token. (TODO) |
---
## User Endpoints
| Method | Endpoint | Description |
|--------|---------------|------------------------------------------------------------|
| GET | `/api/users` | Retrieves a list of all users from the database. |
---
## Chat Endpoints
| Method | Endpoint | Description |
|--------|----------------------------------|-----------------------------------------------------------------|
| GET | `/api/chats` | Retrieves chats for a user (requires an Authorization header). |
| GET | `/api/chat/:id` | Retrieves details of a specific chat using its ID. |
| POST | `/api/chat/create` | Creates a new chat with at least 2 participants. |
| POST | `/api/chat/:id/message` | Sends a message to the specified chat. |
| DELETE | `/api/chat/:id` | Deletes a specific chat by its ID. |
---
## Post Endpoints
| Method | Endpoint | Description |
|--------|----------------------------------|-------------------------------------------------------------------|
| GET | `/api/posts` | Retrieves all posts. |
| GET | `/api/post/:id` | Retrieves a specific post by its ID. |
| POST | `/api/post/create` | Creates a new post. |
| PUT | `/api/post/:id` | Updates an existing post (requires at least one update field). |
| DELETE | `/api/post/:id` | Deletes a specific post by its ID. |
| POST | `/api/post/:id/like` | Likes a specific post. |
---
## Comment Endpoints
| Method | Endpoint | Description |
|--------|-----------------------------------|--------------------------------------------------------------------|
| GET | `/api/post/:id/comments` | Retrieves all comments associated with a specific post. |
| POST | `/api/post/:id/comment` | Adds a new comment to a specified post. |
| PUT | `/api/comment/:id` | Updates an existing comment using its ID. |
| DELETE | `/api/comment/:id` | Deletes a specific comment by its ID. |
| POST | `/api/comment/:id/like` | Likes a specific comment. |
> Note: Replace any `:id` placeholder in the URLs with the actual identifier when making requests.
> Note: Endpoints marked as TODO are placeholders for future implementation.
---
## Base URL
Assuming the server is running on port 8000, the base URL is:
```
http://localhost:8000
```
---
## Index & Documentation Routes
- **GET /**
A simple informational endpoint.
- **Response:** `"For endpoints, use /api/{name}"`
**Example:**
```bash
curl http://localhost:8000/
```
- **GET /api**
Directs users for API documentation.
- **Response:** `"For API Documentation, visit /docs"`
**Example:**
```bash
curl http://localhost:8000/api
```
---
## Account Endpoints
### 1. POST /api/account/login
Log in a user with their username and password.
- **Request Body:**
```json
{
"username": "johndoe",
"password": "secret123"
}
```
- **Response:** On success returns status 200 with body `"Success"`. If unsuccessful, appropriate error messages are returned.
**Example:**
```bash
curl -X POST http://localhost:8000/api/account/login \
-H "Content-Type: application/json" \
-d '{"username": "johndoe", "password": "secret123"}'
```
### 2. POST /api/account/register
Register a new user with all required fields.
- **Request Body:**
```json
{
"username": "johndoe",
"password": "secret123",
"userGroup": "default",
"displayname": "John Doe",
"user_email": "john@example.com",
"firstname": "John",
"surname": "Doe"
}
```
- **Response:** On success returns a status of 200 and a message indicating the user ID registration.
**Example:**
```bash
curl -X POST http://localhost:8000/api/account/register \
-H "Content-Type: application/json" \
-d '{
"username": "johndoe",
"password": "secret123",
"userGroup": "default",
"displayname": "John Doe",
"user_email": "john@example.com",
"firstname": "John",
"surname": "Doe"
}'
```
### Other Account Endpoints
- POST `/api/account/logout`
- POST `/api/account/password/forgot`
- POST `/api/account/password/reset`
- POST `/api/account/password/change`
- POST `/api/account/email/change-email`
- POST `/api/account/email/verify-email`
- POST `/api/account/delete-account`
- POST `/api/account/block`
These endpoints are marked as TODO and currently have no implemented logic.
---
## Auth Endpoints
- GET `/api/auth`
- GET `/api/auth/verify`
- GET `/api/auth/refresh`
These endpoints are also marked as TODO.
---
## User Endpoints
### GET /api/users
Retrieve all users from the database.
- **Response:** JSON array of user objects.
**Example:**
```bash
curl http://localhost:8000/api/users
```
---
## Chat Endpoints
### 1. GET /api/chats
Retrieve all chats for a user. Requires an "Authorization" header and an optional query parameter for userId.
- **Headers:**
- Authorization: Bearer <token> (only required to simulate authentication)
- **Query Parameter:**
- userId (optional; defaults to "1" if not provided)
- **Response:** JSON array of chats for the specified user.
**Example:**
```bash
curl "http://localhost:8000/api/chats?userId=2" \
-H "Authorization: Bearer mytoken123"
```
### 2. GET /api/chat/:id
Retrieve details of a specific chat identified by its ID.
- **Route Parameter:**
- id: Chat ID
- **Response:** JSON object containing chat details.
**Example:**
```bash
curl http://localhost:8000/api/chat/10
```
### 3. POST /api/chat/create
Create a new chat with at least two participants.
- **Request Body:**
```json
{
"participants": [1, 2],
"chatName": "Group Chat"
}
```
- **Response:** Returns status 201 and a JSON object with the newly created "chatId".
**Example:**
```bash
curl -X POST http://localhost:8000/api/chat/create \
-H "Content-Type: application/json" \
-d '{"participants": [1, 2], "chatName": "Group Chat"}'
```
### 4. POST /api/chat/:id/message
Send a message to a specific chat.
- **Route Parameter:**
- id: Chat ID
- **Request Body:**
```json
{
"senderId": 1,
"content": "Hello, world!"
}
```
- **Response:** Returns status 201 and a JSON object with the "messageId" of the new message.
**Example:**
```bash
curl -X POST http://localhost:8000/api/chat/10/message \
-H "Content-Type: application/json" \
-d '{"senderId": 1, "content": "Hello, world!"}'
```
### 5. DELETE /api/chat/:id
Delete a specific chat.
- **Route Parameter:**
- id: Chat ID
- **Response:** Returns status 200 with a confirmation message.
**Example:**
```bash
curl -X DELETE http://localhost:8000/api/chat/10
```
---
## Post Endpoints
### 1. GET /api/posts
Retrieve all posts.
- **Response:** JSON array of posts.
**Example:**
```bash
curl http://localhost:8000/api/posts
```
### 2. GET /api/post/:id
Retrieve a specific post by its ID.
- **Route Parameter:**
- id: Post ID
- **Response:** JSON object representing the post.
**Example:**
```bash
curl http://localhost:8000/api/post/15
```
### 3. POST /api/post/create
Create a new post.
- **Request Body:**
```json
{
"userId": 1,
"postText": "This is a new post",
"postType": "text"
}
```
- **Response:** Returns status 201 with the "postId" of the created post.
**Example:**
```bash
curl -X POST http://localhost:8000/api/post/create \
-H "Content-Type: application/json" \
-d '{"userId": 1, "postText": "This is a new post", "postType": "text"}'
```
### 4. PUT /api/post/:id
Update an existing post. At least one of `postText` or `postType` must be provided.
- **Route Parameter:**
- id: Post ID
- **Request Body:**
```json
{
"postText": "Updated post text",
"postType": "text"
}
```
- **Response:** Returns status 200 with a confirmation message.
**Example:**
```bash
curl -X PUT http://localhost:8000/api/post/15 \
-H "Content-Type: application/json" \
-d '{"postText": "Updated post text", "postType": "text"}'
```
### 5. DELETE /api/post/:id
Delete a specific post.
- **Route Parameter:**
- id: Post ID
- **Response:** Returns status 200 with a message confirming deletion.
**Example:**
```bash
curl -X DELETE http://localhost:8000/api/post/15
```
### 6. POST /api/post/:id/like
Like a specific post.
- **Route Parameter:**
- id: Post ID
- **Request Body:**
```json
{
"userId": 1
}
```
- **Response:** Returns status 200 with a confirmation message.
**Example:**
```bash
curl -X POST http://localhost:8000/api/post/15/like \
-H "Content-Type: application/json" \
-d '{"userId": 1}'
```
---
## Comment Endpoints
### 1. GET /api/post/:id/comments
Retrieve all comments for a specific post.
- **Route Parameter:**
- id: Post ID
- **Response:** JSON array of comments.
**Example:**
```bash
curl http://localhost:8000/api/post/15/comments
```
### 2. POST /api/post/:id/comment
Create a new comment on a specific post.
- **Route Parameter:**
- id: Post ID
- **Request Body:**
```json
{
"userId": 1,
"text": "This is a comment"
}
```
- **Response:** Returns status 201 with the newly created "commentId".
**Example:**
```bash
curl -X POST http://localhost:8000/api/post/15/comment \
-H "Content-Type: application/json" \
-d '{"userId": 1, "text": "This is a comment"}'
```
### 3. PUT /api/comment/:id
Update an existing comment.
- **Route Parameter:**
- id: Comment ID
- **Request Body:**
```json
{
"text": "Updated comment text"
}
```
- **Response:** Returns status 200 with a confirmation message.
**Example:**
```bash
curl -X PUT http://localhost:8000/api/comment/20 \
-H "Content-Type: application/json" \
-d '{"text": "Updated comment text"}'
```
### 4. DELETE /api/comment/:id
Delete a specific comment.
- **Route Parameter:**
- id: Comment ID
- **Response:** Returns status 200 with a confirmation message.
**Example:**
```bash
curl -X DELETE http://localhost:8000/api/comment/20
```
### 5. POST /api/comment/:id/like
Like a specific comment.
- **Route Parameter:**
- id: Comment ID
- **Request Body:**
```json
{
"userId": 1
}
```
- **Response:** Returns status 200 with a confirmation message.
**Example:**
```bash
curl -X POST http://localhost:8000/api/comment/20/like \
-H "Content-Type: application/json" \
-d '{"userId": 1}'
```

View File

@@ -4,5 +4,139 @@
* @description API file for Comments
*/
// +++ IMPORTS ------------------------------------------------------ //
import * as db_utils from "../../database/utils.ts";
import * as helper_utils from "../helpers.ts";
// +++ FUNCTIONS ----------------------------------------------------- //
async function api_getChats(ctx: any): Promise<void> {
try {
const authHeader = ctx.request.headers.get("Authorization");
if (!authHeader) {
helper_utils.errorResponse(ctx, 401, "Authentication Required");
return;
}
// Get userId from query parameter (for testing) or use 1 as default (avoid errors because of userid)
// Assumes 1 is a test account
const userId = ctx.request.url.searchParams.get("userId") || "1";
const chats = await db_utils.getUserChats(userId);
ctx.response.body = chats;
} catch (error) {
helper_utils.errorResponse(ctx, 500, "Error retrieving chats");
console.log(error);
}
}
async function api_getChatById(ctx: any): Promise<void> {
try {
const chatId = ctx.params.id;
if (!chatId) {
helper_utils.errorResponse(ctx, 400, "Chat ID required");
return;
}
const chat = await db_utils.getChatById(chatId);
if (!chat) {
helper_utils.errorResponse(ctx, 404, "Chat not found");
return;
}
ctx.response.body = chat;
} catch (error) {
helper_utils.errorResponse(ctx, 500, "Error retrieving chat");
console.log(error);
}
}
async function api_createChat(ctx: any): Promise<void> {
try {
const body = ctx.request.body;
const result = await body.json();
const { participants, chatName } = result;
if (
!participants || !Array.isArray(participants) || participants.length < 2
) {
helper_utils.errorResponse(
ctx,
400,
"Two people required to create a chat",
);
return;
}
const chatId = await db_utils.createChat(participants, chatName || "");
helper_utils.sendResponse(ctx, {
status: 201,
body: { chatId },
});
} catch (error) {
helper_utils.errorResponse(ctx, 500, "Error creating chat");
console.log(error);
}
}
async function api_sendMessage(ctx: any): Promise<void> {
try {
const chatId = ctx.params.id;
if (!chatId) {
helper_utils.errorResponse(ctx, 400, "Chat ID required");
return;
}
const body = ctx.request.body;
const result = await body.json();
const { senderId, content } = result;
if (!senderId || !content) {
helper_utils.errorResponse(
ctx,
400,
"Sender ID and message content required",
);
return;
}
const messageId = await db_utils.addMessageToChat(
chatId,
senderId,
content,
);
helper_utils.sendResponse(ctx, {
status: 201,
body: { messageId },
});
} catch (error) {
helper_utils.errorResponse(ctx, 500, "Error sending message");
console.log(error);
}
}
async function api_deleteChat(ctx: any): Promise<void> {
try {
const chatId = ctx.params.id;
if (!chatId) {
helper_utils.errorResponse(ctx, 400, "Chat ID required");
return;
}
await db_utils.deleteChat(chatId);
helper_utils.sendResponse(ctx, {
status: 200,
body: { message: "Chat deleted successfully" },
});
} catch (error) {
helper_utils.errorResponse(ctx, 500, "Error deleting chat");
console.log(error);
}
}
export {
api_createChat,
api_deleteChat,
api_getChatById,
api_getChats,
api_sendMessage,
};

View File

@@ -4,10 +4,11 @@
* @description API file for Comments
*/
// +++ IMPORTS ------------------------------------------------------ //
import * as db_utils from "../../database/utils.ts";
import * as helper_utils from "../helpers.ts";
// +++ FUNCTIONS ----------------------------------------------------- //
async function api_getPostComments(ctx: any): Promise<void> {
try {
const postId = ctx.params.id;
@@ -20,6 +21,7 @@ async function api_getPostComments(ctx: any): Promise<void> {
ctx.response.body = comments;
} catch (error) {
helper_utils.errorResponse(ctx, 500, "Error retrieving comments");
console.log(error);
}
}
@@ -52,6 +54,7 @@ async function api_createComment(ctx: any): Promise<void> {
});
} catch (error) {
helper_utils.errorResponse(ctx, 500, "Error creating comment");
console.log(error);
}
}
@@ -79,6 +82,7 @@ async function api_updateComment(ctx: any): Promise<void> {
});
} catch (error) {
helper_utils.errorResponse(ctx, 500, "Error updating comment");
console.log(error);
}
}
@@ -97,6 +101,7 @@ async function api_deleteComment(ctx: any): Promise<void> {
});
} catch (error) {
helper_utils.errorResponse(ctx, 500, "Error deleting comment");
console.log(error);
}
}
@@ -124,5 +129,14 @@ async function api_likeComment(ctx: any): Promise<void> {
});
} catch (error) {
helper_utils.errorResponse(ctx, 500, "Error liking comment");
console.log(error);
}
}
export {
api_createComment,
api_deleteComment,
api_getPostComments,
api_likeComment,
api_updateComment,
};

View File

@@ -4,11 +4,12 @@
* @description API file for Posts
*/
// +++ IMPORTS ------------------------------------------------------ //
import * as db_utils from "../../database/utils.ts";
import * as helper_utils from "../helpers.ts";
import { Context } from "https://deno.land/x/oak@v17.1.2/mod.ts";
// Post functions
// +++ FUNCTIONS ----------------------------------------------------- //
async function api_getPostById(ctx: any): Promise<void> {
try {
const postId = ctx.params.id;
@@ -135,3 +136,11 @@ async function api_likePost(ctx: any): Promise<void> {
helper_utils.errorResponse(ctx, 500, "Error liking post");
}
}
export {
api_createPost,
api_deletePost,
api_getPostById,
api_likePost,
api_updatePost,
};

View File

@@ -1,2 +1,45 @@
/// <reference lib="deno.ns" />
/**
* @author Esad Mustafoski
* @description API file for Users
*/
// +++ IMPORTS ------------------------------------------------------ //
import * as db_utils from "../../database/utils.ts";
import * as helper_utils from "../helpers.ts";
// import * as helper_utils from "../helpers.ts";
import { Context } from "https://deno.land/x/oak@v17.1.2/mod.ts";
// +++ FUNCTIONS ----------------------------------------------------- //
/*async function api_user_getInfo(ctx: any): Promise<void> {
const id = ctx.params.id;
if (!id) {
ctx.response.status = 400;
ctx.response.body = { error: "User ID required" };
return;
}
try {
const user = await db_utils.getAllUserInfoByID(id);
if (user === null || user === undefined) {
helper_utils.errorResponse(ctx, 404, "User not found");
return;
}
ctx.response.body = user;
} catch (error) {
helper_utils.errorResponse(ctx, 500, error as string);
}
}
*/
async function api_getAllUsers(ctx: Context): Promise<void> {
const getUsers = await db_utils.getAllUsersFromDB();
ctx.response.body = getUsers;
}
export {
api_getAllUsers,
// api_user_getInfo
};

View File

@@ -15,7 +15,31 @@ import { oakCors } from "https://deno.land/x/cors@v1.2.2/mod.ts";
import * as db_utils from "../database/utils.ts";
import * as helper_utils from "./helpers.ts";
import {} from "./helpers/mod.ts";
import {
// --- Post --- //
api_getPostById,
api_createPost,
api_updatePost,
api_deletePost,
api_likePost,
// --- Comment --- //
api_getPostComments,
api_createComment,
api_updateComment,
api_deleteComment,
api_likeComment,
// --- User --- //
api_getAllUsers,
// --- Chat --- //
api_createChat,
api_deleteChat,
api_getChatById,
api_getChats,
api_sendMessage,
} from "./helpers/mod.ts";
// +++ VARIABLES / TYPES --------------------------------------------- //
const router = new Router();
@@ -54,18 +78,18 @@ router
.post("/api/account/delete-account", () => {}) // TODO
.post("/api/account/block", () => {}); // TODO
// -- Auth Routes --
// -- Auth Routes -- //
router
.get("/api/auth", () => {}) // TODO
.get("/api/auth/verify", () => {}) // TODO
.get("/api/auth/refresh", () => {}); // TODO
// -- User routes --
// -- User routes -- //
router
.get("/api/users", api_getAllUsers)
.get("/api/user/:id/info", api_user_getInfo);
// .get("/api/user/:id/info", api_user_getInfo);
// -- Chat routes --
// -- Chat routes -- //
router
.get("/api/chats", api_getChats)
.get("/api/chat/:id", api_getChatById)
@@ -73,7 +97,7 @@ router
.post("/api/chat/:id/message", api_sendMessage)
.delete("/api/chat/:id", api_deleteChat);
// -- Post routes --
// -- Post routes -- //
router
.get("/api/posts", api_posts_getAll)
.get("/api/post/:id", api_getPostById)
@@ -82,7 +106,7 @@ router
.delete("/api/post/:id", api_deletePost)
.post("/api/post/:id/like", api_likePost);
// -- Comment Routes --
// -- Comment Routes -- //
router
.get("/api/post/:id/comments", api_getPostComments)
.post("/api/post/:id/comment", api_createComment)
@@ -93,7 +117,7 @@ router
// +++ FUNCTIONS ----------------------------------------------------- //
// ABANDONED FUNCTIONS
// ABANDONED FUNCTIONS //
async function _authenticator(ctx: Context, next: Next): Promise<void> {
const authHeader = ctx.request.headers.get("Authorization");
@@ -104,7 +128,7 @@ async function _authenticator(ctx: Context, next: Next): Promise<void> {
}
// Bearer check
// Bearer is often used for authentication in API's
// Bearer is often used for authentication in API's and is a standard, I check it using RegEx (Regular Expressions)
const match = authHeader.match(/^Bearer (.+)$/);
if (!match) {
ctx.response.status = 401;
@@ -115,7 +139,7 @@ async function _authenticator(ctx: Context, next: Next): Promise<void> {
const token = match[1];
try {
// Token logic missing, not tried or attempted yet.
// Token logic missing, unattempted.
await next();
} catch (error) {
ctx.response.status = 401;
@@ -134,40 +158,13 @@ async function _tokenChecker(ctx: Context, next: Next): Promise<void> {
*/
}
// API: Users
async function api_user_getInfo(ctx: any): Promise<void> {
const id = ctx.params.id;
if (!id) {
ctx.response.status = 400;
ctx.response.body = { error: "User ID required" };
return;
}
try {
const user = await db_utils.getAllUserInfoByID(id);
if (user === null || user === undefined) {
helper_utils.errorResponse(ctx, 404, "User not found");
return;
}
ctx.response.body = user;
} catch (error) {
helper_utils.errorResponse(ctx, 500, error as string);
}
}
async function api_getAllUsers(ctx: Context): Promise<void> {
const getUsers = await db_utils.getAllUsersFromDB();
ctx.response.body = getUsers;
}
// API: Posts
// API: Posts //
async function api_posts_getAll(ctx: Context): Promise<void> {
const posts = await db_utils.getPostsFromDB();
ctx.response.body = posts;
}
// API: login/register
// API: login/register //
async function api_register(ctx: Context): Promise<void> {
try {
const body = ctx.request.body;

View File

@@ -5,6 +5,7 @@
* @file core_utils.ts
*/
// +++ IMPORTS ------------------------------------------------------ //
import { DB, Row } from "https://deno.land/x/sqlite@v3.9.1/mod.ts";
import * as db_create from "../../create_db.ts";

View File

@@ -3,6 +3,7 @@
* @description This file is responsible for creating Functions to easily access the Database, Intended for use in the API
*/
/// <reference lib="deno.ns" />
// +++ IMPORTS ------------------------------------------------------ //
import { DB } from "https://deno.land/x/sqlite@v3.9.1/mod.ts";
import {
@@ -14,13 +15,14 @@ import * as db_create from "./create_db.ts";
// Import all internal utilities with renamed imports to avoid naming conflicts
import {
// --- Account Functions ---
// --- Account Functions --- //
getAllUsersFromDB as getAllUsersFromDBInternal,
getUserByUsername as getUserByUsernameInternal,
// getAllUserInfoByID as getAllUserInfoByIDInternal,
// Accidentally deleted function...
registerUser as registerUserInternal,
// --- Post Functions ---
// --- Post Functions --- //
getPostsFromDB as getPostsFromDBInternal,
getPostById as getPostByIdInternal,
createPost as createPostInternal,
@@ -29,15 +31,16 @@ import {
likePost as likePostInternal,
filterPosts,
// --- Comment Functions ---
// --- Comment Functions --- //
getCommentsFromDB as getCommentsFromDBInternal,
// getCommentsForComments as getCommentsForCommentsInternal,
// Accidentally deleted function...
createComment as createCommentInternal,
updateComment as updateCommentInternal,
deleteComment as deleteCommentInternal,
likeComment as likeCommentInternal,
// --- Chat Functions ---
// --- Chat Functions --- //
getUserChats as getUserChatsInternal,
getChatById as getChatByIdInternal,
getChatMessages as getChatMessagesInternal,
@@ -45,7 +48,7 @@ import {
addMessageToChat as addMessageToChatInternal,
deleteChat as deleteChatInternal,
// --- Mapper Functions ---
// --- Mapper Functions --- //
queryDatabase as queryDatabaseInternal,
} from "./helpers/utils/mod.ts";