Skip to content

api.md

Latest commit

 

History

History
321 lines (295 loc) · 8.32 KB

api.md

File metadata and controls

321 lines (295 loc) · 8.32 KB
Raw

CartBuddy API Specification

This document provides a comprehensive reference of all API endpoints exposed by the CartBuddy Backend service, including routing structures, payload payloads, authentication scopes, and output formats.

Global API Rules

  • All requests should target the prefix /api/v1.
  • Successful requests return a JSON response with a root status of "success" or standard HTTP success codes.
  • Error requests return a JSON response containing status: "fail" or "error", along with a descriptive message and stack (in development mode).
  • Protected endpoints require an Authorization header in the format: Bearer <JWT_ACCESS_TOKEN>.

Authentication Endpoints (/auth)

1. Register User

  • Method & Route: POST /auth/register
  • Authentication Required: No (Public)
  • Description: Registers a new user account. Triggers a background OTP verification email.
  • Request Body: 
    {
  "name": "Alex Johnson",
  "email": "alex.johnson@example.com",
  "password": "password123",
  "phone": "+1234567890"
}
  • Response (201 Created): 
    {
  "status": "success",
  "message": "Registration successful. Please verify your email with the OTP sent.",
  "data": {
    "userId": "66a8d6e326b42b10cf8e3c1a",
    "email": "alex.johnson@example.com",
    "isVerified": false
  }
}

2. Verify OTP

  • Method & Route: POST /auth/verify-otp
  • Authentication Required: No
  • Description: Verifies a user's email with the 6-digit code received.
  • Request Body: 
    {
  "email": "alex.johnson@example.com",
  "code": "489201",
  "purpose": "VERIFY_EMAIL"
}
  • Response (200 OK): 
    {
  "status": "success",
  "message": "Email verified successfully. You can now log in.",
  "data": {
    "isVerified": true,
    "verificationTier": "EMAIL_VERIFIED"
  }
}

3. Log In

  • Method & Route: POST /auth/login
  • Authentication Required: No
  • Description: Logs in a verified user, returns a short-lived Access JWT, and sets a Secure, HttpOnly Refresh JWT cookie.
  • Request Body: 
    {
  "email": "alex.johnson@example.com",
  "password": "password123"
}
  • Response (200 OK): 
    {
  "status": "success",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY2YThkNmUz...",
  "data": {
    "user": {
      "id": "66a8d6e326b42b10cf8e3c1a",
      "name": "Alex Johnson",
      "email": "alex.johnson@example.com",
      "role": "USER",
      "buddyScore": 100
    }
  }
}

4. Refresh Token

  • Method & Route: POST /auth/refresh-token
  • Authentication Required: Yes (via HttpOnly Refresh Cookie)
  • Description: Issues a new JWT Access Token when the previous one expires.
  • Response (200 OK): 
    {
  "status": "success",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY2YThk..."
}

User Endpoints (/users)

1. Get My Profile

  • Method & Route: GET /users/me
  • Authentication Required: Yes
  • Description: Returns detailed info about the currently logged-in user.
  • Response (200 OK): 
    {
  "status": "success",
  "data": {
    "user": {
      "id": "66a8d6e326b42b10cf8e3c1a",
      "name": "Alex Johnson",
      "email": "alex.johnson@example.com",
      "phone": "+1234567890",
      "profileImageUrl": "https://res.cloudinary.com/cartbuddy/image/upload/v1/avatars/alex.jpg",
      "isVerified": true,
      "verificationTier": "EMAIL_VERIFIED",
      "role": "USER",
      "buddyScore": 100,
      "savedAddresses": []
    }
  }
}

2. Update Location

  • Method & Route: PATCH /users/me/location
  • Authentication Required: Yes
  • Description: Updates user's coordinate location for nearby queries.
  • Request Body: 
    {
  "coordinates": [77.5946, 12.9716]
}
  • Response (200 OK): 
    {
  "status": "success",
  "data": {
    "coordinates": [77.5946, 12.9716]
  }
}

Group Endpoints (/groups)

1. Create Shopping Group

  • Method & Route: POST /groups
  • Authentication Required: Yes
  • Description: Initializes a new joint shopping cart group.
  • Request Body: 
    {
  "platform": "Zepto",
  "title": "Weekly Organic Groceries Shared Cart",
  "description": "Sharing delivery fees for organic grocery run. Meet at lobby.",
  "meetingPoint": {
    "type": "Point",
    "coordinates": [77.5946, 12.9716]
  },
  "maxMembers": 5,
  "orderDeadline": "2026-08-30T18:00:00.000Z"
}
  • Response (201 Created): 
    {
  "status": "success",
  "data": {
    "group": {
      "id": "66a8e52a8ef64c12d4a5b91b",
      "platform": "Zepto",
      "title": "Weekly Organic Groceries Shared Cart",
      "status": "ACTIVE",
      "hostId": "66a8d6e326b42b10cf8e3c1a",
      "memberCount": 1,
      "maxMembers": 5,
      "orderDeadline": "2026-08-30T18:00:00.000Z"
    }
  }
}

2. Find Nearby Groups

  • Method & Route: GET /groups/nearby
  • Authentication Required: Yes
  • Description: Queries active shopping groups located within a specified radius (meters).
  • URL Parameters:
    • lat: (Required) Latitude coordinates
    • lng: (Required) Longitude coordinates
    • radius: (Optional, default=1000) Radial distance limit in meters
    • platform: (Optional) Filter groups by shopping vendor (e.g. Blinkit, Costco)
  • Response (200 OK): 
    {
  "status": "success",
  "results": 1,
  "data": {
    "groups": [
      {
        "_id": "66a8e52a8ef64c12d4a5b91b",
        "title": "Weekly Organic Groceries Shared Cart",
        "platform": "Zepto",
        "maxMembers": 5,
        "memberCount": 2,
        "distanceMeters": 142.5
      }
    ]
  }
}

3. Join Group

  • Method & Route: POST /groups/:id/join
  • Authentication Required: Yes
  • Description: Adds the authenticated user as a member of the group.
  • Response (200 OK): 
    {
  "status": "success",
  "message": "Successfully joined the group."
}

4. Complete Group Cart

  • Method & Route: POST /groups/:id/complete
  • Authentication Required: Yes (Host Only)
  • Description: Marks the shared shopping run as ordered/checked out. Unlocks rating submissions for members.
  • Response (200 OK): 
    {
  "status": "success",
  "message": "Group marked as COMPLETED. Member scores can now be rated."
}

Chat & Message Endpoints (/groups/:id/messages)

1. Fetch Chat History

  • Method & Route: GET /groups/:id/messages
  • Authentication Required: Yes (Must be a joined member)
  • Description: Retrieves paginated messages exchanged in the group.
  • Query Params:
    • limit: (Default 50) Max items to return
    • skip: (Default 0) Pagination offset
  • Response (200 OK): 
    {
  "status": "success",
  "results": 2,
  "data": {
    "messages": [
      {
        "_id": "66a8f114c0a52f9b2d8e4f1a",
        "content": "Hey guys, I have added my items to the basket.",
        "senderId": {
          "_id": "66a8d6e326b42b10cf8e3c1a",
          "name": "Alex Johnson",
          "profileImageUrl": ""
        },
        "type": "TEXT",
        "createdAt": "2026-07-29T17:10:00.000Z"
      }
    ]
  }
}

2. Mark Messages as Read

  • Method & Route: POST /groups/:id/messages/read
  • Authentication Required: Yes (Must be a joined member)
  • Description: Marks all unread messages inside the group chat as read by the user.
  • Response (200 OK): 
    {
  "status": "success",
  "message": "Messages marked as read."
}

Notifications Endpoints (/notifications)

1. Get Notifications

  • Method & Route: GET /notifications
  • Authentication Required: Yes
  • Description: Returns lists of push/in-app notifications for the user.
  • Response (200 OK): 
    {
  "status": "success",
  "data": {
    "notifications": [
      {
        "_id": "66a8f89e18b45f18c8e6a32c",
        "title": "New Group Member",
        "message": "Sarah Miller joined your Zepto grocery run.",
        "type": "MEMBER_JOINED",
        "isRead": false,
        "createdAt": "2026-07-29T17:45:00.000Z"
      }
    ]
  }
}