166 lines
4.9 KiB
Markdown
166 lines
4.9 KiB
Markdown
# **Thoughts \- API Design (Version 1\)**
|
|
|
|
## **1\. Overview**
|
|
|
|
This document specifies the RESTful API for the Thoughts platform.
|
|
|
|
* **Base URL:** /api/v1
|
|
* **Data Format:** All requests and responses will be in JSON format.
|
|
* **Authentication:** The API uses two primary methods for authentication:
|
|
1. **JWT (JSON Web Tokens):** For the official web client. The POST /api/v1/auth/login endpoint returns a short-lived JWT. This token must be included in the Authorization: Bearer \<token\> header for all subsequent authenticated requests.
|
|
2. **API Keys:** For third-party applications. Users can generate long-lived API keys. These keys must be included in the Authorization: ApiKey \<key\> header.
|
|
|
|
## **2\. API Endpoints**
|
|
|
|
### **Auth Endpoints**
|
|
|
|
**POST /auth/register**
|
|
|
|
* **Description:** Creates a new user account.
|
|
* **Authentication:** Public.
|
|
* **Request Body:**
|
|
{
|
|
"username": "frutiger",
|
|
"email": "aero@example.com",
|
|
"password": "strongpassword123"
|
|
}
|
|
|
|
* **Success Response:** 201 Created with the new User object (password omitted).
|
|
* **Error Responses:** 400 Bad Request (invalid input), 409 Conflict (username or email already exists).
|
|
|
|
**POST /auth/login**
|
|
|
|
* **Description:** Authenticates a user and returns a JWT.
|
|
* **Authentication:** Public.
|
|
* **Request Body:**
|
|
{
|
|
"username": "frutiger",
|
|
"password": "strongpassword123"
|
|
}
|
|
|
|
* **Success Response:** 200 OK with a JWT.
|
|
{
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
|
}
|
|
|
|
* **Error Responses:** 400 Bad Request, 401 Unauthorized.
|
|
|
|
### **User & Profile Endpoints**
|
|
|
|
**GET /users/{username}**
|
|
|
|
* **Description:** Retrieves the public profile of a user.
|
|
* **Authentication:** Public.
|
|
* **Success Response:** 200 OK with a public User object.
|
|
|
|
**GET /users/me**
|
|
|
|
* **Description:** Retrieves the full profile of the currently authenticated user (including private details like email).
|
|
* **Authentication:** Required (JWT).
|
|
* **Success Response:** 200 OK with the full User object.
|
|
|
|
**PUT /users/me**
|
|
|
|
* **Description:** Updates the profile of the currently authenticated user.
|
|
* **Authentication:** Required (JWT).
|
|
* **Request Body:**
|
|
{
|
|
"displayName": "Frutiger Aero Fan",
|
|
"bio": "Est. 2004",
|
|
"avatarUrl": "https://...",
|
|
"headerUrl": "https://...",
|
|
"customCss": "body { background: blue; }",
|
|
"topFriends": \["username1", "username2"\]
|
|
}
|
|
|
|
* **Success Response:** 200 OK with the updated User object.
|
|
* **Error Responses:** 400 Bad Request.
|
|
|
|
### **Thoughts (Posts) Endpoints**
|
|
|
|
**POST /thoughts**
|
|
|
|
* **Description:** Creates a new thought.
|
|
* **Authentication:** Required (JWT or API Key).
|
|
* **Request Body:**
|
|
{
|
|
"content": "This is my first thought\! \#welcome"
|
|
}
|
|
|
|
* **Success Response:** 201 Created with the new Thought object.
|
|
* **Error Responses:** 400 Bad Request (e.g., content \> 128 chars).
|
|
|
|
**GET /users/{username}/thoughts**
|
|
|
|
* **Description:** Retrieves all thoughts for a specific user, paginated.
|
|
* **Authentication:** Public.
|
|
* **Success Response:** 200 OK with an array of Thought objects.
|
|
|
|
**DELETE /thoughts/{id}**
|
|
|
|
* **Description:** Deletes a thought. The user must be the author.
|
|
* **Authentication:** Required (JWT or API Key).
|
|
* **Success Response:** 204 No Content.
|
|
* **Error Responses:** 403 Forbidden, 404 Not Found.
|
|
|
|
### **Social Endpoints**
|
|
|
|
**POST /users/{username}/follow**
|
|
|
|
* **Description:** Follows a user.
|
|
* **Authentication:** Required (JWT).
|
|
* **Success Response:** 204 No Content.
|
|
* **Error Responses:** 404 Not Found, 409 Conflict (already following).
|
|
|
|
**DELETE /users/{username}/follow**
|
|
|
|
* **Description:** Unfollows a user.
|
|
* **Authentication:** Required (JWT).
|
|
* **Success Response:** 204 No Content.
|
|
* **Error Responses:** 404 Not Found.
|
|
|
|
**GET /feed**
|
|
|
|
* **Description:** Retrieves the main feed for the authenticated user, paginated.
|
|
* **Authentication:** Required (JWT).
|
|
* **Success Response:** 200 OK with an array of Thought objects from followed users.
|
|
|
|
### **Discovery Endpoints**
|
|
|
|
**GET /tags/popular**
|
|
|
|
* **Description:** Retrieves a list of currently popular tags.
|
|
* **Authentication:** Public.
|
|
* **Success Response:** 200 OK with an array of tag strings.
|
|
|
|
**GET /tags/{tagName}**
|
|
|
|
* **Description:** Retrieves a feed of all thoughts with a specific tag, paginated.
|
|
* **Authentication:** Public.
|
|
* **Success Response:** 200 OK with an array of Thought objects.
|
|
|
|
## **3\. Data Models**
|
|
|
|
**User Object (Public)**
|
|
|
|
{
|
|
"username": "frutiger",
|
|
"displayName": "Frutiger Aero Fan",
|
|
"bio": "Est. 2004",
|
|
"avatarUrl": "https://...",
|
|
"headerUrl": "https://...",
|
|
"customCss": "body { background: blue; }",
|
|
"topFriends": \["username1", "username2"\],
|
|
"joinedAt": "2024-01-01T12:00:00Z"
|
|
}
|
|
|
|
**Thought Object**
|
|
|
|
{
|
|
"id": "uuid-v4-string",
|
|
"authorUsername": "frutiger",
|
|
"content": "This is my first thought\! \#welcome",
|
|
"tags": \["welcome"\],
|
|
"createdAt": "2024-01-01T12:01:00Z"
|
|
}
|