bharath/docs/api/API_DESIGN.md

BharathTrucks — API Design Document

Version: 1.0
Date: 2026-05-31
Base URL: https://bharathtrucks.com

---

1. API Architecture

This is a server-rendered application (EJS), so most routes return HTML pages. However, some endpoints return JSON for AJAX interactions (bidding, messaging, notifications).

Route Naming Convention

• Pages: GET /resource → renders HTML
• Actions: POST /resource → form submission, redirects
• API (JSON): GET|POST /api/resource → returns JSON

Authentication

All protected routes use session middleware. Supabase JWT stored in httpOnly cookie.

---

2. Public Routes (No Auth)

Method	Path	Description	Response
GET	/	Landing page	HTML
GET	/loadboard	Public load board (read-only)	HTML
GET	/login	Login page	HTML
POST	/login	Send OTP	Redirect
GET	/verify-otp	OTP input page	HTML
POST	/verify-otp	Verify OTP, create session	Redirect to dashboard
GET	/register	Registration page	HTML
POST	/register	Create account + send OTP	Redirect
GET	/about	About page	HTML
GET	/contact	Contact page	HTML

---

3. Auth Routes

Method	Path	Description	Response
POST	/auth/send-otp	Send OTP to phone	JSON {success, message}
POST	/auth/verify-otp	Verify OTP	JSON {success, redirect}
POST	/auth/logout	Destroy session	Redirect to /
GET	/auth/onboarding	Role-specific profile setup	HTML
POST	/auth/onboarding	Save profile details	Redirect to dashboard

---

4. Load Routes

Pages

Method	Path	Description	Auth	Role
GET	/loads	Load board (authenticated, with filters)	✅	All
GET	/loads/new	Post new load form	✅	Shipper, Broker
GET	/loads/:id	Load detail + bids	✅	All
GET	/loads/:id/edit	Edit load form	✅	Owner

Actions

Method	Path	Description	Auth	Role
POST	/loads	Create new load	✅	Shipper, Broker
POST	/loads/:id	Update load	✅	Owner
POST	/loads/:id/cancel	Cancel load	✅	Owner

API (JSON)

Method	Path	Description	Auth
GET	/api/loads	Load list with filters	✅
GET	/api/loads/search	Search by city/route	Optional

Query Parameters for /api/loads

?origin=Mumbai
&destination=Delhi
&truck_type=open
&min_weight=5
&max_weight=20
&pickup_date=2026-06-01
&status=open
&page=1
&limit=20

Response Format

{
  "success": true,
  "data": {
    "loads": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "pages": 3
    }
  }
}

---

5. Bid Routes

Actions

Method	Path	Description	Auth	Role
POST	/loads/:id/bid	Place bid on load	✅	Driver
POST	/bids/:id/accept	Accept a bid	✅	Load owner
POST	/bids/:id/reject	Reject a bid	✅	Load owner
POST	/bids/:id/withdraw	Withdraw own bid	✅	Bidder

API (JSON)

Method	Path	Description	Auth
GET	/api/loads/:id/bids	Get all bids for a load	✅ (owner/bidder)
GET	/api/bids/my	Get my bid history	✅

Bid Request Body

{
  "amount": 42000,
  "estimated_delivery": "2026-06-05",
  "note": "Can pick up by evening"
}

Bid Rate Limiting

• Free users: 5 bids/day → returns 429 with message after limit
• Premium users: unlimited

---

6. Dashboard Routes

Driver

Method	Path	Description
GET	/driver	Driver dashboard home
GET	/driver/trips	My trips list
GET	/driver/trips/:id	Trip detail
POST	/driver/trips/:id/status	Update trip status
GET	/driver/earnings	Earnings summary
GET	/driver/profile	Edit profile/truck
POST	/driver/profile	Update profile
POST	/driver/availability	Toggle availability

Shipper

Method	Path	Description
GET	/shipper	Shipper dashboard home
GET	/shipper/loads	My posted loads
GET	/shipper/shipments	Active shipments
GET	/shipper/payments	Payment history
POST	/shipper/rate/:tripId	Rate a driver

Broker

Method	Path	Description
GET	/broker	Broker dashboard home
GET	/broker/network	Driver network
POST	/broker/network/add	Add driver to network
GET	/broker/clients	Shipper clients
GET	/broker/commissions	Commission ledger
POST	/broker/commissions/:id/received	Mark commission received
GET	/broker/loads	Loads I've posted

---

7. Messaging Routes

Method	Path	Description	Auth
GET	/messages	Inbox	✅
GET	/messages/:userId	Conversation with user	✅
POST	/api/messages	Send message	✅
GET	/api/messages/:userId	Get conversation (JSON)	✅
POST	/api/messages/read/:id	Mark as read	✅

Message Request Body

{
  "receiver_id": "uuid",
  "load_id": "uuid",
  "content": "Is this load still available?"
}

---

8. Notification Routes

Method	Path	Description	Auth
GET	/api/notifications	Get unread notifications	✅
POST	/api/notifications/read	Mark all as read	✅
POST	/api/notifications/:id/read	Mark one as read	✅

---

9. Admin Routes

Method	Path	Description	Auth
GET	/admin	Admin dashboard	✅ Admin
GET	/admin/users	User management	✅ Admin
POST	/admin/users/:id/suspend	Suspend user	✅ Admin
POST	/admin/users/:id/verify	Verify user	✅ Admin
GET	/admin/loads	All loads	✅ Admin
GET	/admin/metrics	Platform metrics	✅ Admin
POST	/admin/broadcast	Send announcement	✅ Admin

---

10. Shared API Patterns

Success Response

{
  "success": true,
  "data": { ... },
  "message": "Load created successfully"
}

Error Response

{
  "success": false,
  "error": {
    "code": "BID_LIMIT_REACHED",
    "message": "Daily bid limit reached. Upgrade to premium for unlimited bids."
  }
}

HTTP Status Codes Used

Code	Meaning
200	Success
201	Created
302	Redirect (after form submit)
400	Bad request / validation error
401	Not authenticated
403	Not authorized (wrong role)
404	Not found
429	Rate limited
500	Server error

---

11. Middleware Stack

Request → Compression → Helmet → Cookie Parser → Session Check
       → Rate Limiter → Role Check → Controller → Response

Middleware	Purpose
compression	Gzip responses
helmet	Security headers
cookie-parser	Parse auth cookies
authMiddleware	Validate JWT, attach user to req
roleMiddleware(roles)	Check user role access
rateLimiter	Global rate limit (100 req/min)
bidLimiter	Bid-specific limit (5/day free)
errorHandler	Catch-all error formatting

---

12. WhatsApp Share (No API needed)

Load sharing via wa.me links with pre-formatted text:

https://wa.me/?text=🚛 New Load Available!%0A📍 Mumbai → Delhi%0A🏋️ 20 Ton Open Body%0A💰 ₹45,000%0A📅 2 Jun 2026%0A%0AView: https://bharathtrucks.com/loads/abc123

---

All routes follow RESTful conventions. Server-rendered pages for core flows, JSON APIs for dynamic interactions.