From 53738634d35a2cd92cf3f82549498c33df83fe9a Mon Sep 17 00:00:00 2001 From: CosLynx AI Date: Thu, 10 Oct 2024 11:48:41 +0530 Subject: [PATCH] generated file: `docs/API.md` --- docs/API.md | 209 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 docs/API.md diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..4eeab46 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,209 @@ +## Fitness Tracker MVP - API Documentation + +This document outlines the API endpoints for the Fitness Tracker MVP. This API serves as the central communication point between the frontend web application and the backend database. + +### 1. API Endpoints + +#### 1.1 User Authentication (`/api/auth`) + +This endpoint is responsible for handling user authentication using NextAuth.js. + +- **POST `/api/auth/register`** + - Description: Registers a new user with an email and password. + - Request Body: + ```json + { + "email": "user@example.com", + "password": "securepassword" + } + ``` + - Response: + - On Success: `{ "id": "user123", "email": "user@example.com", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }` + - On Failure: `{ "message": "Error registering user" }` +- **POST `/api/auth/signin`** + - Description: Authenticates an existing user with an email and password. + - Request Body: + ```json + { + "email": "user@example.com", + "password": "securepassword" + } + ``` + - Response: + - On Success: `{ "id": "user123", "email": "user@example.com", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }` + - On Failure: `{ "message": "Error logging in" }` +- **POST `/api/auth/signout`** + - Description: Logs out the current user. + - Response: + - On Success: `{ "message": "Logged out successfully" }` + - On Failure: `{ "message": "Error logging out" }` +- **GET `/api/auth/session`** + - Description: Fetches the current user session information, including the user's email and authentication token. + - Response: + - On Success: `{ "user": { "id": "user123", "email": "user@example.com", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }` + - On Failure: `{ "user": null }` + + +#### 1.2 Goals (`/api/goals`) + +This endpoint manages user goals. All requests require authentication (JWT token in the Authorization header). + +- **GET `/api/goals`** + - Description: Retrieves a list of all goals for the current user. + - Response: + - On Success: `{ "goals": [{ "id": 1, "name": "Lose 10 pounds", "targetDate": "2024-06-01", "progress": 3, "target": 10, "userId": 1 }] }` + - On Failure: `{ "message": "Error fetching goals" }` +- **POST `/api/goals`** + - Description: Creates a new goal for the current user. + - Request Body: + ```json + { + "name": "Lose 10 pounds", + "targetDate": "2024-06-01", + "target": 10 + } + ``` + - Response: + - On Success: `{ "id": 1, "name": "Lose 10 pounds", "targetDate": "2024-06-01", "progress": 0, "target": 10, "userId": 1 }` + - On Failure: `{ "message": "Error creating goal" }` +- **GET `/api/goals/:id`** + - Description: Retrieves a specific goal by its ID. + - Response: + - On Success: `{ "id": 1, "name": "Lose 10 pounds", "targetDate": "2024-06-01", "progress": 3, "target": 10, "userId": 1 }` + - On Failure: `{ "message": "Goal not found" }` +- **PUT `/api/goals/:id`** + - Description: Updates a specific goal by its ID. + - Request Body: + ```json + { + "name": "Lose 10 pounds", + "targetDate": "2024-06-01", + "target": 10 + } + ``` + - Response: + - On Success: `{ "id": 1, "name": "Lose 10 pounds", "targetDate": "2024-06-01", "progress": 3, "target": 10, "userId": 1 }` + - On Failure: `{ "message": "Error updating goal" }` +- **DELETE `/api/goals/:id`** + - Description: Deletes a specific goal by its ID. + - Response: + - On Success: (Empty response with status 204) + - On Failure: `{ "message": "Error deleting goal" }` + +#### 1.3 Progress Entries (`/api/progress`) + +This endpoint manages user progress entries, representing workouts, weight, and other activity data. All requests require authentication. + +- **GET `/api/progress`** + - Description: Retrieves a list of progress entries for the current user. + - Response: + - On Success: `{ "progressEntries": [{ "id": 1, "value": 175, "date": "2024-04-01", "goalId": 1, "userId": 1 }] }` + - On Failure: `{ "message": "Error fetching progress entries" }` +- **POST `/api/progress`** + - Description: Creates a new progress entry for the current user. + - Request Body: + ```json + { + "goalId": 1, + "value": 175, + "date": "2024-04-01" + } + ``` + - Response: + - On Success: `{ "id": 1, "value": 175, "date": "2024-04-01", "goalId": 1, "userId": 1 }` + - On Failure: `{ "message": "Error creating progress entry" }` +- **GET `/api/progress/:id`** + - Description: Retrieves a specific progress entry by its ID. + - Response: + - On Success: `{ "id": 1, "value": 175, "date": "2024-04-01", "goalId": 1, "userId": 1 }` + - On Failure: `{ "message": "Progress entry not found" }` +- **PUT `/api/progress/:id`** + - Description: Updates a specific progress entry by its ID. + - Request Body: + ```json + { + "value": 175, + "date": "2024-04-01", + "goalId": 1 + } + ``` + - Response: + - On Success: `{ "id": 1, "value": 175, "date": "2024-04-01", "goalId": 1, "userId": 1 }` + - On Failure: `{ "message": "Error updating progress entry" }` +- **DELETE `/api/progress/:id`** + - Description: Deletes a specific progress entry by its ID. + - Response: + - On Success: (Empty response with status 204) + - On Failure: `{ "message": "Error deleting progress entry" }` + +#### 1.4 Users (`/api/users`) + +This endpoint manages user profiles (primarily for administrative purposes). All requests require authentication. + +- **GET `/api/users`** + - Description: Retrieves a list of all users (for administrative purposes). + - Response: + - On Success: `{ "users": [{ "id": 1, "email": "user1@example.com", "password": "hashed_password", "goals": [] }] }` + - On Failure: `{ "message": "Error fetching users" }` +- **GET `/api/users/me`** + - Description: Retrieves the current user's profile information. + - Response: + - On Success: `{ "id": 1, "email": "user1@example.com", "password": "hashed_password", "goals": [] }` + - On Failure: `{ "message": "Error fetching user profile" }` +- **PUT `/api/users/:id`** + - Description: Updates a specific user's profile information (email and password). + - Request Body: + ```json + { + "email": "updated@example.com", + "password": "newpassword" + } + ``` + - Response: + - On Success: `{ "id": 1, "email": "updated@example.com", "password": "hashed_password", "goals": [] }` + - On Failure: `{ "message": "Error updating user profile" }` + +#### 1.5 Stripe Webhooks (`/api/webhooks`) + +This endpoint handles Stripe webhooks for future payment integrations. + +- **POST `/api/webhooks/stripe`** + - Description: Receives and processes Stripe webhooks for subscription management and payments. + - Response: + - On Success: (Empty response with status 200) + - On Failure: `{ "message": "Error processing Stripe webhook" }` + +### 2. Authentication + +- All requests to protected endpoints (`/api/goals`, `/api/progress`, `/api/users`) require a valid JWT token in the `Authorization` header. +- The token is generated upon successful user registration or login using `pages/api/auth/[...nextauth].ts`. +- The token contains user ID and other necessary data. + +### 3. Error Handling + +- All API endpoints implement robust error handling: + - Invalid requests (e.g., missing required fields, invalid data formats) result in a 400 Bad Request response with an error message. + - Unauthorized requests (no or invalid JWT token) result in a 401 Unauthorized response. + - Resource not found (e.g., goal not found) result in a 404 Not Found response. + - Server-side errors (e.g., database errors) result in a 500 Internal Server Error response. +- Error messages provide informative details to help debug issues. + +### 4. API Versioning + +- For future expansion, API versioning is implemented through URL prefixes (e.g., `/api/v2/goals`). +- Backwards compatibility is maintained for existing endpoints. + +### 5. Security + +- **Authentication:** The API uses JWT for secure authentication, preventing unauthorized access. +- **Input Validation:** All incoming data is validated to prevent malicious inputs and ensure data integrity. +- **Data Encryption:** Sensitive data (e.g., passwords) is encrypted at rest and in transit. + +### 6. Performance Optimization + +- **Caching:** API responses are cached to reduce server load and improve response times. +- **Database Optimization:** Database queries are optimized for performance. + +### Conclusion + +This API documentation provides a comprehensive overview of the Fitness Tracker MVP's API structure and functionality. This well-documented and secure API forms the foundation for communication between the frontend application and backend database, ensuring a seamless and robust user experience. \ No newline at end of file