API Design

API Documentation

1. Add User

POST /api/users

Create a new user account in the system.

Request Body

{
  "username": "string (required, 3-30 chars)"
}

Response

Success (201 Created)

{
  "user_id": 12345,
  "username": "alice_smith",
  "created_at": "2024-01-15T10:30:00Z"
}

Error (400 Bad Request)

{
  "error": "Username already exists"
}

---

2. Fetch All Users

GET /api/users

Retrieve a list of all users in the system.

Request Example

GET /api/users

Response

Success (200 OK)

{
  "users": [
    {
      "user_id": "12345",
      "username": "alice_smith",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "user_id": "12346",
      "username": "bob_jones",
      "created_at": "2024-01-14T09:15:00Z"
    }
  ],
  "total_count": 25000
}

---

🔗 3. Follow User

POST /api/follow

Create a follow relationship between two users.

Request Body

{
  "follower_user_id": "12345",
  "target_user_id": "12346",
  "action": "follow"
}

Response

Success (201 Created) 201 Created

{
  "follower_id": 12345,
  "following_id": 12346,
  "created_at": "2024-01-15T11:45:00Z"
}

400 Bad Request

{
  "error": "Cannot follow yourself"
}

409 Conflict

{
  "error": "Already following this user"
}

Error (400 Bad Request)

{
  "success": false,
  "error": "Cannot follow yourself",
  "error_code": "SELF_FOLLOW_NOT_ALLOWED"
}

Error (409 Conflict)

{
  "success": false,
  "error": "Already following this user",
  "error_code": "ALREADY_FOLLOWING"
}

4. Get User Followers

Get user's followers list

Endpoint

GET /api/{user_id}/followers

Request Body

GET /api/12345/followers?limit=50

Response

Success (200 OK)

{
  "followers": [
    {
      "user_id": 101,
      "username": "happy_runner_456"
    },
    {
      "user_id": 102,
      "username": "creative_builder_789"
    }
  ],
  "total_count": 150,
  "next_cursor": "eyJsYXN0X2lkIjoxMDJ9",
  "has_more": true
}

Error (404 Not Found)

{
  "error": "User not found",
  "error_code": "USER_NOT_FOUND"
}

Error (500 Internal Server Error)

{
  "error": "Failed to get followers",
  "error_code": "INTERNAL_ERROR"
}

5. Get User Following

Get user's following list

Endpoint

GET /api/{user_id}/following

Request Body

GET /api/12345/following?limit=50

Response

Success (200 OK)

{
  "following": [
    {
      "user_id": 201,
      "username": "brilliant_artist_111"
    },
    {
      "user_id": 202,
      "username": "super_developer_222"
    },
    {
      "user_id": 203,
      "username": "excellent_designer_333"
    }
  ],
  "total_count": 75,
  "next_cursor": "eyJsYXN0X2lkIjoyMDN9",
  "has_more": true
}

Error (404 Not Found)

{
  "error": "User not found",
  "error_code": "USER_NOT_FOUND"
}

Error (500 Internal Server Error)

{
  "error": "Failed to get following",
  "error_code": "INTERNAL_ERROR"
}

---

📝 6. Create Post

POST /api/posts

Create a new post and trigger fan-out to followers' timelines.

Request Body

{
  "user_id": 123456,
  "content": "string (required, 1-280 chars)",
  "visibility": "public|private (optional, default: public)"
}

Response

Success (201 Created)

{
  "post_id": "post_789",
  "user_id": 12345,
  "content": "Beautiful sunset today! 🌅",
  "created_at": "2024-01-15T18:30:00Z"
}

Error (400 Bad Request)

{
  "error": "Content cannot be empty"
}

---

📱 7. Get Timeline

GET /api/timeline/{user_id}

Retrieve the timeline for a specific user (posts from users they follow).

Path Parameters

• user_id (required): ID of the user whose timeline to fetch

Response

Success (200 OK)

{
  "timeline": [
    {
      "post_id": "post_789",
      "user_id": 12346,
      "username": "bob_jones",
      "content": "Just finished a great workout! 💪",
      "created_at": "2024-01-15T17:45:00Z"
    },
    {
      "post_id": "post_790",
      "user_id": 12345,
      "username": "alice_smith",
      "content": "Working on an exciting new project",
      "created_at": "2024-01-15T16:30:00Z"
    }
  ],
  "total_count": 156
}

Error (404 Not Found)

{
  "error": "User not found"
}