API Documentation
This document describes all APIs used and required by the application: existing internal routes, the backend contract consumed by the frontend, entities and their relations, authentication, and admin panel CRUD endpoints.
1. Authentication & Access Control
- Auth: NextAuth with Credentials (plus optional Google and GitHub providers).
- Session strategy: JWT. User object extended with role: "admin" | "user".
- Middleware-protected routes:
/admin(requires admin),/user(requires session).
NextAuth endpoints
- POST/GET
/api/auth/[...nextauth]— handled by NextAuth - GET
/api/me— current session snapshot - GET
/api/admin— requires admin role
2. Internal API Routes (built-in)
GET /api/me
Returns whether the user is authenticated and the session payload.
Response 200
{
"authenticated": boolean,
"session": {
"user": {
"name": string | null,
"email": string | null,
"image": string | null,
"role": "admin" | "user"
} | null,
"expires": string
} | null
}GET /api/admin
Requires an authenticated session with role=admin.
Response 200
{ "message": "Welcome, admin!", "email": string | null, "role": "admin" }
Response 401
{ "error": "Unauthorized" }3. Frontend → Backend Contract (consumed by lib/api.ts)
When NEXT_PUBLIC_API_URL is set, the frontend calls these endpoints on your backend. If not set, the app serves mock data with the same shapes.
3.1 Content
GET /content/hero-banner
Response 200: { data: { title: string; subtitle: string; image: string; ctaText: string; ctaLink: string }, success: true }3.2 Categories
GET /categories
GET /categories/{slug}
// Category type
interface Category { id: string; name: string; slug: string; description: string; image: string; productCount: number }
// Responses
{ data: Category[], success: true }
{ data: Category, success: true }3.3 Products
GET /products?category={slug}&featured=true|false&limit={n}&page={n}
GET /products/{slug}
interface Product {
id: string
title: string
description: string
price: number
images: string[]
category: string // references Category.slug
slug: string
inStock: boolean
featured?: boolean
}
{ data: Product[], success: true }
{ data: Product, success: true }3.4 Reviews
GET /products/{id}/reviews
GET /reviews/featured?limit={n}
interface Review { id: string; productId: string; customerName: string; rating: number; comment: string; createdAt: string }
{ data: Review[], success: true }Note: reviews use productId that maps to Product.id (product detail uses slug).
3.5 Blog
GET /blog?limit={n}&page={n}
GET /blog/{slug}
interface BlogPost {
id: string
title: string
slug: string
excerpt: string
content: string
featuredImage: string
publishedAt: string
seo: { title: string; description: string; keywords: string[] }
}
{ data: BlogPost[], success: true }
{ data: BlogPost, success: true }3.6 CRM & Leads
POST /crm/events
Body: { type: "whatsapp_chat", productId: string, productTitle: string, source: "frontend", timestamp: ISOString }
POST /crm/leads
Body: { name: string, email: string, message: string, phone?: string, source: "contact_form", timestamp: ISOString }
Response: { data: null, success: true, message?: string }3.7 Cart
POST /cart/add
Body: { productId: string, quantity: number, price: number }
GET /cart
Response: { data: { productId: string; quantity: number; price: number }[], success: true }3.8 Newsletter
POST /newsletter/subscribe
Body: { email: string, source: "website", timestamp: ISOString }
Response: { data: null, success: true }3.9 Search
GET /search/products?q={query}&category={slug}&minPrice={n}&maxPrice={n}&sortBy={field}
Response: { data: Product[], success: true }4. Entities & Relations
Canonical schemas derived from the UI and existing types.
// Wrapper
interface ApiResponse<T = any> { data: T; message?: string; success: boolean }
// Core entities
interface Category { id: string; name: string; slug: string; description: string; image: string; productCount: number }
interface Product {
id: string
title: string
description: string
price: number
images: string[]
category: string // FK -> Category.slug
slug: string
inStock: boolean
featured?: boolean
}
interface Review { id: string; productId: string; customerName: string; rating: number; comment: string; createdAt: string } // FK -> Product.id
interface BlogPost { id: string; title: string; slug: string; excerpt: string; content: string; featuredImage: string; publishedAt: string; seo: { title: string; description: string; keywords: string[] } }
interface CartItem { productId: string; quantity: number; price: number }
// Auth
interface AppUser { id: string; name: string | null; email: string | null; role: "admin" | "user" }
// Admin/Orders (UI-derived)
interface Order { id: string; customer: string; email: string; total: number; status: "processing" | "delivered" | "pending" | "cancelled" }- Product.category references Category.slug. Review.productId references Product.id.
- BlogPost.seo contains nested metadata used for SEO rendering.
5. Admin Panel CRUD Endpoints (required by UI)
These endpoints power the Admin pages under /admin. Protect all with admin role.
// Products
GET /admin/products -> { data: Product[], success: true }
POST /admin/products Body: Product (without id for create) -> { data: Product, success: true }
GET /admin/products/{id} -> { data: Product, success: true }
PUT /admin/products/{id} Body: Partial<Product> -> { data: Product, success: true }
DELETE/admin/products/{id} -> { data: null, success: true }
// Categories
GET /admin/categories -> { data: Category[], success: true }
POST /admin/categories Body: Category -> { data: Category, success: true }
GET /admin/categories/{id} -> { data: Category, success: true }
PUT /admin/categories/{id} Body: Partial<Category> -> { data: Category, success: true }
DELETE/admin/categories/{id} -> { data: null, success: true }
// Blog
GET /admin/blog -> { data: BlogPost[], success: true }
POST /admin/blog Body: BlogPost -> { data: BlogPost, success: true }
GET /admin/blog/{id} -> { data: BlogPost, success: true }
PUT /admin/blog/{id} Body: Partial<BlogPost> -> { data: BlogPost, success: true }
DELETE/admin/blog/{id} -> { data: null, success: true }
// Users
GET /admin/users -> { data: AppUser[], success: true }
GET /admin/users/{id} -> { data: AppUser, success: true }
PUT /admin/users/{id} Body: { role?: "admin"|"user" } -> { data: AppUser, success: true }
// Orders
GET /admin/orders -> { data: Order[], success: true }
GET /admin/orders/{id} -> { data: Order, success: true }
PUT /admin/orders/{id} Body: { status: Order["status"] } -> { data: Order, success: true }6. Error Handling
Errors should use HTTP status codes. Body should still follow the wrapper where feasible.
// Error shape
{ "data": null, "success": false, "message": string }7. Environment Variables
NEXT_PUBLIC_API_URL— base URL for the backend powering endpoints in section 3.NEXTAUTH_SECRET— JWT secret for auth.GITHUB_ID/GITHUB_SECRET,GOOGLE_ID/GOOGLE_SECRET— optional OAuth providers.