Skip to content

API.md

Latest commit

 

History

History
287 lines (224 loc) · 4.81 KB

API.md

File metadata and controls

287 lines (224 loc) · 4.81 KB

GoalGenius API Documentation

This document provides detailed information about the GoalGenius API endpoints. All API routes are prefixed with /api.

Authentication

All API endpoints require authentication. The application uses Better Auth for authentication, supporting both GitHub and Google OAuth providers.

Response Format

All responses are returned in JSON format. Successful responses will contain the requested data, while error responses will have the following structure:

{
  "error": "Error message description"
}

Common HTTP Status Codes

  • 200: Success
  • 201: Created
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 500: Internal Server Error

API Endpoints

Goals

Get All Goals

GET /api/goals?userId={userId}

Query Parameters:

  • userId (required): The ID of the user whose goals to retrieve

Response:

[
  {
    "id": "uuid",
    "userId": "string",
    "title": "string",
    "description": "string?",
    "category": "health" | "career" | "learning" | "relationships",
    "timeFrame": "string",
    "status": "not-started" | "in-progress" | "completed",
    "progress": number,
    "dueDate": "string?",
    "createdAt": "string",
    "updatedAt": "string"
  }
]

Create Goal

POST /api/goals

Request Body:

{
  "userId": "string",
  "title": "string",
  "description": "string?",
  "category": "health" | "career" | "learning" | "relationships",
  "timeFrame": "string",
  "status": "not-started" | "in-progress" | "completed",
  "progress": number,
  "dueDate": "string?"
}

Response: The created goal object

Update Goal

PUT /api/goals

Request Body:

{
  "id": "uuid",
  "title": "string?",
  "description": "string?",
  "category": "string?",
  "timeFrame": "string?",
  "status": "string?",
  "progress": number?,
  "dueDate": "string?"
}

Response: The updated goal object

Delete Goal

DELETE /api/goals?id={goalId}

Query Parameters:

  • id (required): The ID of the goal to delete

Response:

{
  "success": true
}

Todos

Get All Todos

GET /api/todos?userId={userId}

Query Parameters:

  • userId (required): The ID of the user whose todos to retrieve

Create Todo

POST /api/todos

Request Body:

{
  "userId": "string",
  "title": "string",
  "description": "string?",
  "priority": "low" | "medium" | "high",
  "status": "pending" | "in-progress" | "completed",
  "dueDate": "string?"
}

Update Todo

PUT /api/todos

Delete Todo

DELETE /api/todos?id={todoId}

Notes

Get All Notes

GET /api/notes?userId={userId}

Create Note

POST /api/notes

Update Note

PUT /api/notes

Delete Note

DELETE /api/notes?id={noteId}

Milestones

Get All Milestones

GET /api/milestones?goalId={goalId}

Create Milestone

POST /api/milestones

Update Milestone

PUT /api/milestones

Delete Milestone

DELETE /api/milestones?id={milestoneId}

Check-ins

Get All Check-ins

GET /api/checkins?userId={userId}

Create Check-in

POST /api/checkins

Update Check-in

PUT /api/checkins

Delete Check-in

DELETE /api/checkins?id={checkinId}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. Here are some common error scenarios:

Validation Errors (400)

{
  "error": "Missing required fields"
}

Authentication Errors (401)

{
  "error": "Unauthorized access"
}

Not Found Errors (404)

{
  "error": "Resource not found"
}

Server Errors (500)

{
  "error": "Failed to process request"
}

Rate Limiting

The API is protected by Cloudflare's rate limiting. Please be mindful of the following limits:

  • Maximum of 100 requests per minute per IP
  • Maximum of 1000 requests per hour per IP

Development and Testing

For local development and testing:

  1. Set up your environment variables:

    cp .dev.vars.example .dev.vars
cp .env.local.example .env.local

  2. Start the development server:

    pnpm dev

  3. The API will be available at http://localhost:3000/api

API Versioning

The current API version is v1. All endpoints are currently unversioned, but future breaking changes will be introduced under new versioned paths (e.g., /api/v2/).

Support

If you encounter any issues or need help with the API:

  1. Check the documentation (coming soon)
  2. Create an issue on GitHub

Last updated: 2025