api_design.md

# API Design Document

## Overview
This document outlines the RESTful API endpoints for the Lin application backend. The API will be implemented using Flask and will follow REST conventions.

## Authentication
All endpoints (except authentication endpoints) require a valid JWT token in the Authorization header:
```
Authorization: Bearer <token>
```

## Error Handling
All endpoints will return appropriate HTTP status codes:
- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized
- 404: Not Found
- 500: Internal Server Error

Error responses will follow this format:
```json
{
  "error": "Error message",
  "code": "ERROR_CODE"
}
```

## Endpoints

### Authentication

#### Register User
- **POST** `/api/auth/register`
- **Description**: Register a new user
- **Request Body**:
```json
{
  "email": "string",
  "password": "string",
  "confirm_password": "string"
}
```
- **Response**:
```json
{
  "message": "User registered successfully",
  "user": {
    "id": "string",
    "email": "string"
  }
}
```

#### Login User
- **POST** `/api/auth/login`
- **Description**: Authenticate a user
- **Request Body**:
```json
{
  "email": "string",
  "password": "string"
}
```
- **Response**:
```json
{
  "token": "string",
  "user": {
    "id": "string",
    "email": "string"
  }
}
```

#### Logout User
- **POST** `/api/auth/logout`
- **Description**: Logout current user
- **Response**:
```json
{
  "message": "Logged out successfully"
}
```

#### Get Current User
- **GET** `/api/auth/user`
- **Description**: Get current authenticated user
- **Response**:
```json
{
  "user": {
    "id": "string",
    "email": "string"
  }
}
```

### Sources

#### Get All Sources
- **GET** `/api/sources`
- **Description**: Get all sources for the current user
- **Response**:
```json
{
  "sources": [
    {
      "id": "string",
      "user_id": "string",
      "source": "string",
      "category": "string",
      "last_update": "datetime"
    }
  ]
}
```

#### Add Source
- **POST** `/api/sources`
- **Description**: Add a new source
- **Request Body**:
```json
{
  "source": "string"
}
```
- **Response**:
```json
{
  "message": "Source added successfully",
  "source": {
    "id": "string",
    "user_id": "string",
    "source": "string",
    "category": "string",
    "last_update": "datetime"
  }
}
```

#### Delete Source
- **DELETE** `/api/sources/{id}`
- **Description**: Delete a source
- **Response**:
```json
{
  "message": "Source deleted successfully"
}
```

### Social Accounts

#### Get All Accounts
- **GET** `/api/accounts`
- **Description**: Get all social media accounts for the current user
- **Response**:
```json
{
  "accounts": [
    {
      "id": "string",
      "user_id": "string",
      "social_network": "string",
      "account_name": "string",
      "created_at": "datetime"
    }
  ]
}
```

#### Add Account
- **POST** `/api/accounts`
- **Description**: Add a new social media account
- **Request Body**:
```json
{
  "account_name": "string",
  "social_network": "string"
}
```
- **Response**:
```json
{
  "message": "Account added successfully",
  "account": {
    "id": "string",
    "user_id": "string",
    "social_network": "string",
    "account_name": "string",
    "created_at": "datetime"
  }
}
```

#### Delete Account
- **DELETE** `/api/accounts/{id}`
- **Description**: Delete a social media account
- **Response**:
```json
{
  "message": "Account deleted successfully"
}
```

### Posts

#### Get All Posts
- **GET** `/api/posts`
- **Description**: Get all posts for the current user
- **Query Parameters**:
  - `published` (boolean): Filter by published status
- **Response**:
```json
{
  "posts": [
    {
      "id": "string",
      "user_id": "string",
      "social_account_id": "string",
      "text_content": "string",
      "image_content_url": "string",
      "is_published": "boolean",
      "created_at": "datetime",
      "scheduled_at": "datetime"
    }
  ]
}
```

#### Generate Post
- **POST** `/api/posts/generate`
- **Description**: Generate a new post using AI
- **Request Body**:
```json
{
  "user_id": "string"
}
```
- **Response**:
```json
{
  "content": "string"
}
```

#### Create Post
- **POST** `/api/posts`
- **Description**: Create a new post
- **Request Body**:
```json
{
  "social_account_id": "string",
  "text_content": "string",
  "image_content_url": "string",
  "scheduled_at": "datetime"
}
```
- **Response**:
```json
{
  "message": "Post created successfully",
  "post": {
    "id": "string",
    "user_id": "string",
    "social_account_id": "string",
    "text_content": "string",
    "image_content_url": "string",
    "is_published": "boolean",
    "created_at": "datetime",
    "scheduled_at": "datetime"
  }
}
```

#### Publish Post
- **POST** `/api/posts/{id}/publish`
- **Description**: Publish a post to social media
- **Response**:
```json
{
  "message": "Post published successfully"
}
```

#### Delete Post
- **DELETE** `/api/posts/{id}`
- **Description**: Delete a post
- **Response**:
```json
{
  "message": "Post deleted successfully"
}
```

### Schedules

#### Get All Schedules
- **GET** `/api/schedules`
- **Description**: Get all schedules for the current user
- **Response**:
```json
{
  "schedules": [
    {
      "id": "string",
      "social_account_id": "string",
      "schedule_time": "string",
      "adjusted_time": "string",
      "created_at": "datetime"
    }
  ]
}
```

#### Create Schedule
- **POST** `/api/schedules`
- **Description**: Create a new schedule
- **Request Body**:
```json
{
  "social_account_id": "string",
  "schedule_time": "string",  // Format: "Monday 18:00"
  "days": ["string"]          // Array of days
}
```
- **Response**:
```json
{
  "message": "Schedule created successfully",
  "schedule": {
    "id": "string",
    "social_account_id": "string",
    "schedule_time": "string",
    "adjusted_time": "string",
    "created_at": "datetime"
  }
}
```

#### Delete Schedule
- **DELETE** `/api/schedules/{id}`
- **Description**: Delete a schedule
- **Response**:
```json
{
  "message": "Schedule deleted successfully"
}