api docs improved

Ankur5522 · Ankur5522 · commit 1e86d678edbe · 2025-03-01T11:45:51.000+05:30
diff --git a/docs/API/01-Overview.md b/docs/API/01-Overview.md
@@ -1,18 +1,32 @@
 # Overview
+## Introduction
 
-# Introduction
-
-This API is built using [Hono](https://hono.dev/) and serves as a starter kit for building scalable and secure backend applications. It includes authentication, protected routes, rate limiting, and structured routing.
+Our API is built using **Hono**, a fast and lightweight web framework designed to handle API requests efficiently. The API adheres to **RESTful principles**, ensuring a consistent and intuitive interface for users. It integrates **Redis** for rate limiting and caching, enhancing performance and preventing abuse. The architecture is structured to be easily extendable and secure.
 
 ## Features
-- **Authentication** with middleware
-- **Protected routes** for secure endpoints
-- **Rate limiting** using Redis
-- **RESTful API structure**
-- **Support for API clients** (Postman, Fetch API, cURL)
+
+### 1. **Hono Framework**
+- **Lightweight and Fast**: Hono is optimized for speed and minimal overhead, making it ideal for serverless environments like Cloudflare Workers.
+- **Web Standards Compliance**: Built on web standards, Hono ensures compatibility across different platforms.
+
+### 2. **Protected Routes**
+- **Security via Middlewares**: The API uses middlewares to protect routes from unauthorized access. This includes authentication and authorization checks to ensure only authorized users can access sensitive data.
+
+### 3. **Redis-based Rate Limiting**
+- **Preventing Abuse**: Redis is used to implement rate limiting, preventing excessive requests from a single source and protecting against potential attacks.
+
+### 4. **Authentication Middleware**
+- **Protecting Routes**: Authentication middleware ensures that only authenticated users can access protected routes.
+
+### 5. **Integration with TanStack Query**
+- **Efficient Data Fetching and Mutations**: TanStack Query is used to optimize data fetching and mutations, reducing unnecessary requests and improving overall performance.
 
 ## Base URL
-The API base URL depends on your environment:
 
-- **Development:** `http://localhost:3000/api`
-- **Production:** `<your-deployed-url>/api`
+The base URL of the API varies depending on the environment:
+
+- **Development**: `http://localhost:3000/api`
+- **Production**: `<your-deployed-url>/api`
+
+
+
diff --git a/docs/API/02-Adding-new-endpoint.md b/docs/API/02-Adding-new-endpoint.md
@@ -1,15 +1,78 @@
-# Adding new endpoint
+# Adding a New Endpoint to the API
 
-# New Endpoints
+## Overview
 
-The API exposes various endpoints for interacting with the backend.
+This guide will walk you through adding a new API endpoint using the Hono framework for your server-side application. Follow the steps below to create new routes and handle API requests efficiently.
 
-## 1. **Public Endpoints**
-### `GET /api/hello`
-Returns a simple greeting message.
+### Steps to Add a New Endpoint
+
+#### 1. **Navigate to the `routes/api.ts` File**
+
+The primary location for defining your API routes is in the `server/routes/api.ts` file. This is where all core API endpoints should be defined.
+
+#### 2. **Define the New Route**
+
+Use Hono’s routing methods (`app.get`, `app.post`, `app.put`, etc.) to define a new route. Each route corresponds to an HTTP method and a URL pattern.
+
+#### 3. **Implement Logic in the Handler Function**
+
+In the handler function, implement the necessary logic to process the request. You can access request data, query parameters, headers, and more.
+
+#### 4. **Return a JSON Response**
+
+Ensure that your endpoint responds with a JSON object, especially for API responses. Hono's context (`c`) makes it easy to return structured JSON responses.
+
+## Creating a New Router File
+
+If your application grows and you need to organize your routes better, you can create a new file for each module (e.g., routes/users.ts). This can help maintain a clean structure as the project expands.
+
+### Steps to create a new router file
+
+#### 1. **Create a new file**
+
+In the server/routes/ directory. For example, you can create server/routes/users.ts for user-related routes.
+
+#### 2. **Define your routes**
+
+using Hono’s routing methods (app.get, app.post, etc.) in the new file.
+
+#### 3. **Import and use the new router**
+
+ in the main server configuration file (e.g., server.ts).
+
+
+### Example of creating a ` Users ` router
+
+Create a file, `server/routes/users.ts`, where you define routes related to user management:
 
-**Request:**
 ```ts
-app.get('/hello', (c) => {
-  return c.json({ message: 'Hello from Hono API!' });
+import { Hono } from 'hono';
+
+const app = new Hono();
+
+app.get('/api/users', (c) => {
+  // Logic to retrieve all users
+  const users = getAllUsers();  // Assume this function fetches user data
+  return c.json(users);  // Return the response as JSON
 });
+
+export default app;
+```
+
+Then, ensure that the `users.ts` router is imported and used in the main server setup `server.ts`
+
+File: ` server.ts `
+
+```ts
+import { Hono } from 'hono';
+import users from './routes/users.ts'
+
+const app = new Hono();
+
+app.router('/api/users', users);
+
+export default app;
+```
+
+You can also define a router file for defining all the routes and then importing the file in `server.ts`. For more best 
+practices regarding hono you can refer to their official docs [Hono Best Practices](https://hono.dev/docs/guides/best-practices).
diff --git a/docs/API/03-Protected-routes.md b/docs/API/03-Protected-routes.md
@@ -1,14 +1,38 @@
 # Protected Routes
 
-Some API routes require user authentication to access.
+Hono has built-in support for [middlewares](https://hono.dev/docs/guides/middleware), which are functions that can be used to modify the context or execute code before or after a route handler is executed.
 
-## Middleware-Based Protection
+That's how we can secure our API endpoints from unauthorized access. Below are some examples of you can leverage middlewares to protect your API routes.
 
-We use the `authMiddleware` to enforce authentication for specific routes.
+## Authenticated access
 
-### **Middleware: `authMiddleware`**
+After validating the user's authentication status using next-auth, it automatically stores the user data in sessions object. This allows us to access the user's information in subsequent middleware and procedures without having to re-validate the session.
+
+We have already provided with a auth middleware which yo can find at `server/middlewares/auth-middleware.ts` which provides with basic authenticated access.
+
+```ts
+import type { Context, Next } from 'hono'
+import { auth } from '@/lib/auth'
+import { log } from '@/lib/logger'
+
+export const authMiddleware = async (c: Context, next: Next) => {
+    try {
+        const session = await auth();
+
+        if (!session) {
+            return c.json({ error: 'Unauthorized' }, 401)
+        }
+
+        c.set('user', session.user) // Attach user data to context
+        await next()
+    } catch (err) {
+        console.error('Error in auth middleware:', err)
+        log("error", "Error in auth middleware: " + err)
+        return c.json({ error: 'Internal server error' }, 500)
+    }
+}
+```
 
-Located at `src/server/middlewares/auth-middleware.ts`, this middleware ensures that only authenticated users can access protected routes.
 
 ### **Applying Middleware**
 
@@ -19,3 +43,39 @@ app.get("/protected", authMiddleware, (c) => {
   const user: any = c.get("user");
   return c.json({ message: "Protected API Data", name: user.name });
 });
+```
+
+## Feature-based access
+
+To implement feature-based access, such as role-based access control (RBAC), you can define a middleware that checks the user's role before allowing access to certain routes.
+
+Here's an example of how you can create a role-based access middleware:
+
+```ts
+import type { Context, Next } from 'hono'
+
+export const roleMiddleware = (requiredRole: string) => {
+  return async (c: Context, next: Next) => {
+    const user: any = c.get('user')
+
+    if (!user || user.role !== requiredRole) {
+      return c.json({ error: 'Forbidden' }, 403)
+    }
+
+    await next()
+  }
+}
+```
+
+### **Applying Role-Based Middleware**
+
+To apply role-based access control to an endpoint, attach `roleMiddleware` with the required role to the route definition:
+
+```ts
+app.get("/admin", authMiddleware, roleMiddleware('admin'), (c) => {
+  return c.json({ message: "Admin API Data" });
+});
+```
+
+In this example, only users with the role `admin` will be able to access the `/admin` route.
+
diff --git a/docs/API/04-Using-API-client.md b/docs/API/04-Using-API-client.md
@@ -1,6 +1,6 @@
 # Using Api Client
 
-This app supports various HTTP methods, and all requests are handled in `src/app/api/[...routes]/route.tsx`.
+This app supports various HTTP methods, and all requests are handled in `src/app/api/[...routes]/route.tsx`. It exports all the related HTTP methods so you only need to make the api call using your preferred method and you are good to go.
 
 ## Available Methods
 ```ts
@@ -12,21 +12,123 @@ export const PATCH = handle(app);
 export const OPTIONS = handle(app);
 ```
 
+Each exported method is responsible for handling the corresponding HTTP request and routing it to the appropriate logic within the app.
+
 ## Example GET Request using TanStack Query
 
-To call a GET request using TanStack Query, you can use the `useQuery` hook as shown below:
+TanStack Query is a powerful library for managing server state in React applications. You can use it to call API endpoints like the one you’ve defined in your route.tsx file.
+
+Using TanStack Query in combination with your Hono API client allows you to manage server-state in a declarative way while handling various HTTP methods such as GET, POST, PUT, DELETE, and PATCH. By leveraging TanStack Query, It can simplify state management, automatically handle caching and refetching.
+
+Here’s how you can perform a GET request to fetch data using TanStack Query:
 
 ```ts
 import { useQuery } from '@tanstack/react-query';
 
 const fetchHello = async () => {
-    const res = await fetch("/api/hello");
-    if (!res.ok) throw new Error("Failed to fetch data");
-    return res.json();
-  };
+  const res = await fetch("/api/hello");
+  if (!res.ok) {
+    throw new Error("Failed to fetch data");
+  }
+  return res.json();
+};
 
-const { data: helloData } = useQuery({
+const HelloComponent = () => {
+  const { data: helloData, error, isLoading } = useQuery({
     queryKey: ["hello"],
-    queryFn: fetchHello,
-});
-```
+    queryFn: fetchHello, 
+  });
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (error instanceof Error) {
+    return <div>Error: {error.message}</div>;
+  }
+  return <div>{helloData?.message}</div>;
+};
+
+export default HelloComponent;
+
+```
+## Handling POST, PUT, DELETE Requests with TanStack Query
+
+Just like with GET requests, you can also use TanStack Query for making POST, PUT, DELETE, or PATCH requests to your API. Below are some examples of how to handle these HTTP methods.
+
+### Example: Making a POST Request
+
+For sending data (e.g., creating a new resource), use the `mutate` function from the `useMutation` hook:
+
+```ts
+import { useMutation } from '@tanstack/react-query';
+
+const createUser = async (userData: { name: string }) => {
+  const res = await fetch("/api/users", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(userData),
+  });
+
+  if (!res.ok) throw new Error("Failed to create user");
+  return res.json();
+};
+
+const UserCreationComponent = () => {
+  const mutation = useMutation({
+    mutationFn: createUser,
+  });
+
+  const handleCreateUser = () => {
+    const newUser = { name: "John Doe" };
+    mutation.mutate(newUser);
+  };
+
+  return (
+    <div>
+      <button onClick={handleCreateUser}>Create User</button>
+      {mutation.isLoading && <div>Creating user...</div>}
+      {mutation.isError && <div>Error: {mutation.error.message}</div>}
+      {mutation.isSuccess && <div>User created successfully!</div>}
+    </div>
+  );
+};
+
+export default UserCreationComponent;
+```
+
+### Example: Making a PUT Request
+
+For updating a resource:
+
+```ts
+const updateUser = async (userId: string, userData: { name: string }) => {
+  const res = await fetch(`/api/users/${userId}`, {
+    method: "PUT",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(userData),
+  });
+
+  if (!res.ok) throw new Error("Failed to update user");
+  return res.json();
+};
+```
+
+### Example: Making a DELETE Request
+
+For deleting a resource:
+
+```ts
+const deleteUser = async (userId: string) => {
+  const res = await fetch(`/api/users/${userId}`, {
+    method: "DELETE",
+  });
+
+  if (!res.ok) throw new Error("Failed to delete user");
+  return res.json();
+};
+```
diff --git a/docs/API/05-Mutations.md b/docs/API/05-Mutations.md
