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:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Endpoints

Authentication

Register User

• POST /api/auth/register
• Description: Register a new user
• Request Body:

{
  "email": "string",
  "password": "string",
  "confirm_password": "string"
}

• Response:

{
  "message": "User registered successfully",
  "user": {
    "id": "string",
    "email": "string"
  }
}

Login User

• POST /api/auth/login
• Description: Authenticate a user
• Request Body:

{
  "email": "string",
  "password": "string"
}

• Response:

{
  "token": "string",
  "user": {
    "id": "string",
    "email": "string"
  }
}

Logout User

• POST /api/auth/logout
• Description: Logout current user
• Response:

{
  "message": "Logged out successfully"
}

Get Current User

• GET /api/auth/user
• Description: Get current authenticated user
• Response:

{
  "user": {
    "id": "string",
    "email": "string"
  }
}

Sources

Get All Sources

• GET /api/sources
• Description: Get all sources for the current user
• Response:

{
  "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:

{
  "source": "string"
}

• Response:

{
  "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:

{
  "message": "Source deleted successfully"
}

Social Accounts

Get All Accounts

• GET /api/accounts
• Description: Get all social media accounts for the current user
• Response:

{
  "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:

{
  "account_name": "string",
  "social_network": "string"
}

• Response:

{
  "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:

{
  "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:

{
  "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:

{
  "user_id": "string"
}

• Response:

{
  "content": "string"
}

Create Post

• POST /api/posts
• Description: Create a new post
• Request Body:

{
  "social_account_id": "string",
  "text_content": "string",
  "image_content_url": "string",
  "scheduled_at": "datetime"
}

• Response:

{
  "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:

{
  "message": "Post published successfully"
}

Delete Post

• DELETE /api/posts/{id}
• Description: Delete a post
• Response:

{
  "message": "Post deleted successfully"
}

Schedules

Get All Schedules

• GET /api/schedules
• Description: Get all schedules for the current user
• Response:

{
  "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:

{
  "social_account_id": "string",
  "schedule_time": "string",  // Format: "Monday 18:00"
  "days": ["string"]          // Array of days
}

• Response:

{
  "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:

{
  "message": "Schedule deleted successfully"
}