Skip to content

Docs: Align API documentation with implementation #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Devasy wants to merge 1 commit into from
Closed

Docs: Align API documentation with implementation #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 71 additions & 2 deletions docs/auth-service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,9 @@
| POST | `/auth/password/reset/request` | Send password-reset email link |
| POST | `/auth/password/reset/confirm` | Set new password via reset token |
| POST | [`/auth/token/verify`](#4-access-token-verification-auto-login) | Verify access token and auto-login |
| POST | `/auth/token` | OAuth2 compatible token login (for Swagger UI/OpenAPI) |

*Refer to the [Micro-Level API Specification](./micro-plan.md#1-authentication-service) for more details on password reset endpoints.*
*Refer to the [Micro-Level API Specification](./micro-plan.md#1-authentication-service) for more details on password reset endpoints. Basic request/response for password reset are also summarized below.*

## 1. Email/Password Sign-Up & Sign-In

Expand Down Expand Up @@ -186,7 +187,75 @@ This endpoint helps in providing a seamless login experience if a valid session

---

## 5. Client-Side Persistence & UX
## 5. Password Reset Endpoints

These endpoints manage the password reset flow.

### a. Request Password Reset

* **Endpoint**: `POST /auth/password/reset/request`
* **Description**: Initiates the password reset process by sending a reset link/token to the user's email.
* **Request**:
```json
{
"email": "[email protected]"
}
```
* **Response (Success)**:
```json
200 OK
{
"success": true,
"message": "If the email exists, a reset link has been sent"
}
```

### b. Confirm Password Reset

* **Endpoint**: `POST /auth/password/reset/confirm`
* **Description**: Allows a user to set a new password using a valid reset token.
* **Request**:
```json
{
"reset_token": "valid_reset_token_string",
"new_password": "newSecurePassword123"
}
```
* **Response (Success)**:
```json
200 OK
{
"success": true,
"message": "Password has been reset successfully"
}
```

---

## 6. OAuth2 Token Endpoint (Primarily for Swagger/OpenAPI)

This endpoint is standard for OAuth2 password flow and primarily used by tools like Swagger UI for interactive API documentation. It allows users to authenticate within the Swagger interface to test protected endpoints.

* **Endpoint**: `POST /auth/token`
* **Description**: OAuth2 compatible token login. Expects `username` (as email) and `password` in form-data.
* **Request (form-data)**:
```
[email protected]
password=userpassword
```
* **Response (Success)**:
```json
200 OK
{
"access_token": "...jwt...",
"token_type": "bearer"
}
```
*(Note: This endpoint, as implemented in `auth/routes.py` for Swagger, returns only an access_token. The main `/auth/login/email` should be used by clients for full auth token pair.)*

---

## 7. Client-Side Persistence & UX

* **On App Launch**

Expand Down
38 changes: 21 additions & 17 deletions docs/expense-service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,19 @@ Content-Type: application/json
"createdAt": "2024-01-15T18:30:00Z",
"updatedAt": "2024-01-15T18:30:00Z"
},
"settlements": null,
"groupSummary": null
}
```

**Note:** The `settlements` and `groupSummary` fields in the response are placeholders in the current implementation and will return `null`. Populating these fields with relevant data (e.g., initial settlements generated by this expense, updated group balance summary) is a **TODO**. The example below shows the intended structure once implemented.

```json
// Example of intended future response structure:
{
"expense": {
// ... expense details ...
},
"settlements": [
{
"_id": "65f1a2b3c4d5e6f7a8b9c0d2",
Expand All @@ -131,33 +144,21 @@ Content-Type: application/json
"amount": 125.00,
"status": "completed",
"createdAt": "2024-01-15T18:30:00Z"
},
{
"_id": "65f1a2b3c4d5e6f7a8b9c0d3",
"expenseId": "65f1a2b3c4d5e6f7a8b9c0d1",
"groupId": "65f1a2b3c4d5e6f7a8b9c0d0",
"payerId": "user_a_id",
"payeeId": "user_b_id",
"payerName": "Alice",
"payeeName": "Bob",
"amount": 125.00,
"status": "pending",
"createdAt": "2024-01-15T18:30:00Z"
}
// ... similar entries for user_c and user_d
// ... other settlements related to this expense
],
"groupSummary": {
"totalExpenses": 2750.00,
"totalSettlements": 12,
"optimizedSettlements": [
"totalExpenses": 2750.00, // Updated total expenses for the group
"totalSettlements": 12, // Updated total number of settlements in the group
"optimizedSettlements": [ // Potentially updated optimized settlements for the group
{
"fromUserId": "user_b_id",
"toUserId": "user_a_id",
"amount": 125.00,
"fromUserName": "Bob",
"toUserName": "Alice"
}
// ... optimized settlement suggestions
// ... other optimized settlement suggestions
]
}
}
Expand Down Expand Up @@ -300,6 +301,7 @@ Content-Type: multipart/form-data
"url": "https://storage.example.com/attachments/unique_attachment_key_string.jpg"
}
```
**Note:** The current implementation simulates file upload and generates a key and URL. Actual persistent file storage (e.g., to a cloud bucket) is **TODO**.

#### Get/Download an Attachment

Expand All @@ -312,6 +314,8 @@ Authorization: Bearer <access_token>

Returns the file stream.

**Note:** This endpoint is **TODO** and currently returns a `501 Not Implemented` error. The functionality to retrieve the actual file stream is not yet implemented.

### 2. Settlement Management

#### Manually Record Payment
Expand Down
39 changes: 39 additions & 0 deletions docs/group-service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,7 @@ App --> User: Show group details
```json
{ "error": "You have unsettled balances of ₹123.45" }
```
**Note**: The check for outstanding balances before allowing a user to leave a group is a **TODO** in the current service implementation. The endpoint will currently allow leaving regardless of balance.

---

Expand All @@ -194,3 +195,41 @@ App --> User: Show group details

*All require `Authorization: Bearer <token>` (managed by [Auth Service](./auth-service.md)).*
*Interactions with expenses and settlements are handled by the [Expense Service](./expense-service.md).*

---

Comment on lines +198 to +200
Copy link
Contributor

@coderabbitai coderabbitai bot Jun 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Anchor in summary table is now stale

Row 15 in the summary table still links to #4-crud-endpoints-recap even though the dedicated section is now §5 List Group Members. Update the link target to keep in-page navigation working.

-|   GET  | [`/groups/{group_id}/members`](#4-crud-endpoints-recap)             | List members                        |
+|   GET  | [`/groups/{group_id}/members`](#5-list-group-members)               | List members                        |

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents 
In docs/group-service.md around lines 198 to 200, the anchor link in row 15 of
the summary table incorrectly points to #4-crud-endpoints-recap instead of the
updated section §5 List Group Members. Update the href attribute of the anchor
tag in that row to #5-list-group-members to ensure the in-page navigation link
is correct and functional.

## 5. List Group Members

Retrieves a list of all members within a specified group, including their user details.

* **Endpoint**: `GET /groups/{group_id}/members`
* **Authorization**: `Bearer <access_token>` (User must be a member of the group)

**Successful Response (200 OK):**
Returns a list of member objects.

```json
[
{
"userId": "usr_123abc",
"role": "admin",
"joinedAt": "2024-01-15T10:00:00Z",
"name": "Jane Doe",
"imageUrl": "https://example.com/profile_jane.jpg"
},
{
"userId": "usr_456def",
"role": "member",
"joinedAt": "2024-01-16T11:30:00Z",
"name": "John Smith",
"imageUrl": "https://example.com/profile_john.jpg"
}
]
```

Each object in the list contains:
- `userId`: The unique identifier of the member.
- `role`: The role of the member in the group (e.g., "admin", "member").
- `joinedAt`: The timestamp when the member joined the group.
- `name`: The name of the user (fetched from user profile).
- `imageUrl`: The profile image URL of the user (fetched from user profile).
10 changes: 5 additions & 5 deletions docs/user-service.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Retrieves the profile information for the currently authenticated user.
"image_url": "https://example.com/profile.jpg",
"currency": "USD",
"created_at": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-16T12:30:00Z"
"updated_at": "2024-01-16T12:30:00Z"
}
```

Expand Down Expand Up @@ -89,13 +89,13 @@ Allows the currently authenticated user to update their profile information and
```json
{
"user": {
"_id": "507f191e810c19729de860ea",
"id": "507f191e810c19729de860ea",
"name": "Johnathan Doe",
"email": "[email protected]",
"imageUrl": "https://example.com/profiles/johnathan_doe_new.jpg",
"image_url": "https://example.com/profiles/johnathan_doe_new.jpg",
"currency": "EUR",
"createdAt": "2024-01-10T10:00:00Z",
"updatedAt": "2025-06-11T10:15:00Z"
"created_at": "2024-01-10T10:00:00Z",
"updated_at": "2025-06-11T10:15:00Z"
}
}
```
Expand Down