BuyWhere API Documentation Site — Design Specification
Overview
Design specification for the BuyWhere developer documentation site at docs.buywhere.ai. Target users: AI agent developers, e-commerce integrators, and data scientists building commerce applications.
1. Information Architecture
1.1 Navigation Structure
┌─────────────────────────────────────────────────────────────────┐
│ [Logo] BuyWhere Docs [Search...🔍] [Theme] [GitHub] │
└─────────────────────────────────────────────────────────────────┘
┌─────────────┬───────────────────────────────────────────────────┐
│ │ │
│ GETTING │ Content Area │
│ STARTED │ │
│ ├─ Quickstart│ # Endpoint Title │
│ ├─ Auth │ │
│ └─ Rate │ Short description of what this endpoint does. │
│ Limits │ │
│ │ ## Request │
│ API │ ```http │
│ REFERENCE │ GET /v1/products │
│ ├─ Products│ ``` │
│ ├─ Search │ │
│ ├─ Compare │ ## Parameters │
│ └─ ... │ | Name | Type | Required | Description | │
│ │ |--------|--------|----------|------------------|│
│ GUIDES │ │
│ ├─ Agents │ │
│ ├─ LangChain│ │
│ └─ Webhooks│ ## Response │
│ │ ```json │
│ SDKS │ { "items": [...] } │
│ ├─ Python │ ``` │
│ ├─ JavaScript │
│ └─ ... │ [Try it ▶] [Expand full response ▼] │
│ │ │
│ CHANGELOG │ │
│ │ │
└─────────────┴───────────────────────────────────────────────────┘
1.2 URL Structure
| Section | URL Pattern | Description |
|---|---|---|
| Landing | / | Marketing + getting started overview |
| Quickstart | /quickstart | 5-minute tutorial |
| API Reference | /api/{resource} | e.g., /api/products, /api/search |
| Guides | /guides/{topic} | e.g., /guides/agents, /guides/langchain |
| SDKs | /sdks/{lang} | e.g., /sdks/python, /sdks/javascript |
| Changelog | /changelog | Version history |
| Search | /search?q= | Full-text doc search |
1.3 Sidebar Hierarchy
Getting Started (collapsible)
- Quickstart
- Authentication
- Rate Limits & Tiers
- Error Codes
API Reference (collapsible, expandable subgroups)
- Products (
/v1/products,/v2/products) - Search (
/v1/search,/v2/search) - Categories
- Deals
- Compare
- Trending
- Merchants
- Webhooks
Guides (collapsible)
- AI Agent Integration
- LangChain + BuyWhere
- CrewAI Tools
- Webhook Setup
- Batch Operations
SDKs (collapsible)
- Python
- JavaScript/TypeScript
- Go
Resources
- Changelog
- Status Page
- Postman Collection
2. Component Library
2.1 Endpoint Card
┌──────────────────────────────────────────────────────────────┐
│ GET /v1/products [Try] │
├──────────────────────────────────────────────────────────────┤
│ Search and filter products across all indexed merchants. │
│ │
│ auth: API key required • tier: standard • version: v1 │
└──────────────────────────────────────────────────────────────┘
States:
- Default: neutral border
- New/Updated: green left border + "NEW" or "UPDATED" badge
- Deprecated: amber left border + "DEPRECATED" badge
- Beta: purple left border + "BETA" badge
Visual Specs:
- Background:
var(--bg-card)(white in light,#1a1a2ein dark) - Border: 1px solid
var(--border)(#e5e7eb/#2d2d44) - Border-left: 4px solid
var(--accent)(#0066ff) - Border-radius: 8px
- Padding: 16px
- Method badge: GET (green), POST (blue), PATCH (amber), DELETE (red)
- Font: method = monospace bold, path = monospace regular
2.2 Code Block
Variants: bash, python, javascript, json, http, sql
┌──────────────────────────────────────────────────────────────┐
│ curl ✕ │
├──────────────────────────────────────────────────────────────┤
│ curl -X GET "https://api.buywhere.ai/v1/products" \ │
│ -H "X-API-Key: {api_key}" │
└──────────────────────────────────────────────────────────────┘
Visual Specs:
- Background:
var(--code-bg)(#f8f8f8/#0d0d1a) - Font: JetBrains Mono, 13px, line-height 1.5
- Syntax highlighting: custom theme matching dark/light mode
- Copy button: top-right, icon only, appears on hover
- Language tab: top-left for multi-language examples
- Line numbers: optional, left gutter
- Horizontal scroll for long lines
- Border-radius: 6px
2.3 Parameter Table
┌─────────────────────────────────────────────────────────────────────────┐
│ Parameters │
├────────────┬────────┬────────────┬──────────────────────────────────────┤
│ Name │ Type │ Required │ Description │
├────────────┼────────┼────────────┼──────────────────────────────────────┤
│ q │ string │ Yes │ Search query, max 500 chars │
│ limit │ int │ No (10) │ Results per page, 1-100 │
│ offset │ int │ No (0) │ Pagination offset │
│ min_price │ float │ No │ Minimum price filter │
│ max_price │ float │ No │ Maximum price filter │
│ source │ string │ No │ Filter by merchant (e.g., shopee_sg)│
└────────────┴────────┴────────────┴──────────────────────────────────────┘
Visual Specs:
- Header row:
var(--table-header-bg), bold text - Alternating rows:
var(--bg-row-alt)for zebra striping - Required badge: red dot or "required" text in red
- Type badges:
string(green),int(blue),float(purple),bool(amber) - Border: 1px solid
var(--border), collapse - Padding: 8px 12px per cell
- Overflow: horizontal scroll on mobile
2.4 Response Preview
┌─────────────────────────────────────────────────────────────┐
│ Response [Expand ▼] [Copy ✕] │
├─────────────────────────────────────────────────────────────┤
│ { │
│ "total": 248, │
│ "limit": 3, │
│ "offset": 0, │
│ "items": [ │
│ { │
│ "id": 78234, │
│ "name": "Sony WH-1000XM5", │
│ ──── "price": "449.00", [truncated] ───│
│ } │
│ ], │
│ "has_more": true │
│ } │
└─────────────────────────────────────────────────────────────┘
Visual Specs:
- Collapsible with "Expand" toggle
- Truncation indicator for large responses
- Syntax highlighted JSON matching code block theme
- Copy button
- Key field highlighting (optional)
2.5 Try It Panel
┌──────────────────────────────────────────────────────────────┐
│ Try It │
├──────────────────────────────────────────────────────────────┤
│ Base URL: https://api.buywhere.ai │
│ │
│ Endpoint: GET /v1/products │
│ │
│ Parameters: │
│ ┌─ q ─────────────────────────────────────┐ │
│ │ wireless headphones │ │
│ └─────────────────────────────────────────┘ │
│ ┌─ limit ─┐ ┌─ offset ─┐ │
│ │ 10 │ │ 0 │ │
│ └─────────┘ └──────────┘ │
│ │
│ Headers: │
│ ┌─ X-API-Key ─────────────────────────────────────┐ │
│ │ •••••••••••••••••••••••••••••• │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ [Send Request ▶] │
│ │
│ Status: 200 OK | Time: 124ms │
│ │
│ Response body: │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ { "total": 248, ... } │ │
│ └─────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
2.6 Search Component
In-header search:
- Full-text search across all documentation
- Keyboard shortcut:
Cmd/Ctrl + K - Modal overlay with instant results
- Results grouped by section (Guides, API, SDKs)
- Highlight matching terms
Visual Specs:
- Modal: centered, 600px max-width, backdrop blur
- Input: large (18px), auto-focus
- Results: icon + title + breadcrumb path
- Keyboard navigation support
2.7 Version Badge
┌─────────────────────────────────────────────┐
│ Version: [v2 ▼] [Changelog →] │
└─────────────────────────────────────────────┘
- Dropdown to switch between v1, v2 (if multi-version)
- Changelog link
- Deprecation notice for old versions
2.8 Sidebar Navigation
States:
- Default: text
var(--text-secondary) - Hover: background
var(--bg-hover), textvar(--text-primary) - Active: background
var(--accent-subtle), textvar(--accent), left border accent - Expanded group: chevron rotated 90°
Specs:
- Padding: 8px 12px per item
- Group headers: uppercase, 11px, letter-spacing 0.5px
- Nested items: 12px left indent per level
- Sticky positioning on scroll
3. Page Layouts
3.1 Landing Page (/)
┌─────────────────────────────────────────────────────────────────┐
│ [Logo] Docs API SDKs Pricing Blog [Login] [GitHub] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Agent-Native Product Catalog API │
│ │
│ Build AI shopping agents that search, compare, and buy │
│ across 10,000+ merchants in Southeast Asia. │
│ │
│ [Get API Key] [Read the Docs] [View on GitHub] │
│ │
│ ─────────────────────────────────────────────────────────────│
│ │
│ Trusted by agents building the future of commerce: │
│ [Logo] [Logo] [Logo] [Logo] │
│ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Quick Links │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Quickstart │ │ API Reference│ │ SDKs │ │
│ │ Get running │ │ All endpoints│ │ Python, JS, │ │
│ │ in 5 minutes │ │ documented │ │ Go, and more │ │
│ │ [→] │ │ [→] │ │ [→] │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Featured Guides │
│ ┌────────────────────────┐ ┌────────────────────────┐ │
│ │ AI Agent Integration │ │ Building a Price │ │
│ │ Learn how to integrate │ │ Comparison Agent │ │
│ │ BuyWhere into your agent │ │ Use /compare endpoint │ │
│ │ stack. │ │ to build comparison. │ │
│ │ [Read more →] │ │ [Read more →] │ │
│ └────────────────────────┘ └────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
3.2 Endpoint Reference Page (/api/products)
┌─────────────────────────────────────────────────────────────────┐
│ Products API │
├─────────────────────────────────────────────────────────────────┤
│ The Products API provides access to BuyWhere's catalog of │
│ 1M+ products from merchants across Southeast Asia. │
├─────────────────────────────────────────────────────────────────┤
│ Base URL: https://api.buywhere.ai │
│ Auth: X-API-Key header │
│ Version: v1 (stable) | v2 (beta) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Search Products │
│ GET /v1/products │
├─────────────────────────────────────────────────────────────────┤
│ Search and filter products across all indexed merchants. │
│ Supports full-text search, price filters, category filters, │
│ and merchant filtering. │
└─────────────────────────────────────────────────────────────────┘
[Code Example ▼] [Parameters ▼] [Response ▼] [Errors ▼]
## Code Examples
[curl ▼] [python ▼] [javascript ▼]
┌─────────────────────────────────────────────────────────────┐
│ curl -X GET "https://api.buywhere.ai/v1/products" \ │
│ -H "X-API-Key: $BUYWHERE_API_KEY" \ │
│ -d "q=wireless+headphones" \ │
│ -d "limit=10" │
└─────────────────────────────────────────────────────────────┘
## Parameters
| Name | Type | Required | Description |
|----------|--------|----------|----------------------------------|
| q | string | Yes | Search query, max 500 chars |
| limit | int | No (10) | Results per page, 1-100 |
| offset | int | No (0) | Pagination offset |
| min_price| float | No | Minimum price filter |
| max_price| float | No | Maximum price filter |
| source | string | No | Filter by merchant |
## Response
```json
{
"total": 248,
"limit": 10,
"offset": 0,
"items": [...],
"has_more": true
}
[Try it ▶]
───────────────────────────────────────────────────────────────
Get Product by ID
GET /v1/products/{id}
[Similar structure...]
───────────────────────────────────────────────────────────────
[← Previous: Categories] [Next: Search →]
### 3.3 Guide Page (`/guides/agents`)
┌─────────────────────────────────────────────────────────────────┐
│ Guides » AI Agent Integration │
├─────────────────────────────────────────────────────────────────┤
│ │
│ # Building AI Shopping Agents with BuyWhere │
│ │
│ This guide shows how to integrate BuyWhere into your AI agent │
│ stack for product search, comparison, and purchase flows. │
│ │
│ ## Prerequisites │
│ │
│ - BuyWhere API key │
│ - Python 3.10+ or Node.js 18+ │
│ - LangChain or similar agent framework │
│ │
│ ## Installation │
│ │
│ bash │ │ pip install buywhere │ │ │
│ │
│ ## Quick Integration │
│ │
│ [Content continues with step-by-step code examples...] │
│ │
└─────────────────────────────────────────────────────────────────┘
│ On this page │
│ ├─ Prerequisites │
│ ├─ Installation │
│ ├─ Quick Integration │
│ ├─ Advanced: Batch Operations │
│ └─ Error Handling │
└─────────────────────────────────────────────────────────────────┘
### 3.4 Changelog Page (`/changelog`)
┌─────────────────────────────────────────────────────────────────┐ │ Changelog │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ # API Changelog │ │ │ │ Updates, additions, and deprecations to the BuyWhere API. │ │ │ │ [All versions ▼] [Subscribe to updates] │ │ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ## v2.4.0 — April 15, 2026 │ │ [NEW] Batch product details endpoint │ │ [NEW] Cursor-based pagination support │ │ [IMPROVED] Search response latency reduced by 40% │ │ [FIXED] Rate limit header consistency │ │ │ │ ───────────────────────────────────────────────────────────── │ │ │ │ ## v2.3.0 — March 28, 2026 │ │ [NEW] Webhook support for price alerts │ │ [IMPROVED] Image search accuracy │ │ [DEPRECATED] /v1/search/semantic (use /v2/search/semantic) │ │ │ │ ───────────────────────────────────────────────────────────── │ │ │ │ ## v2.2.0 — March 10, 2026 │ │ ... │ │ │ └─────────────────────────────────────────────────────────────────┘
---
## 4. Dark Mode Support
### 4.1 Color Tokens
**Light Mode:**
--bg-primary: #ffffff --bg-secondary: #f9fafb --bg-card: #ffffff --bg-hover: #f3f4f6 --text-primary: #111827 --text-secondary: #6b7280 --border: #e5e7eb --accent: #0066ff --accent-hover: #0052cc --code-bg: #f8f8f8 --table-header: #f3f4f6 --success: #10b981 --warning: #f59e0b --error: #ef4444
**Dark Mode:**
--bg-primary: #0f0f1a --bg-secondary: #1a1a2e --bg-card: #1a1a2e --bg-hover: #252540 --text-primary: #f9fafb --text-secondary: #9ca3af --border: #2d2d44 --accent: #4d94ff --accent-hover: #66a3ff --code-bg: #0d0d1a --table-header: #1f1f35 --success: #34d399 --warning: #fbbf24 --error: #f87171
### 4.2 Theme Toggle
- Position: header, right side
- Icons: sun (light) / moon (dark) / system
- Persist preference in localStorage
- Respect `prefers-color-scheme` on first visit
- Smooth 200ms transition on toggle
---
## 5. Responsive Design
### 5.1 Breakpoints
| Name | Range | Sidebar | Content |
|------|-------|---------|---------|
| Mobile | < 640px | Hidden (hamburger menu) | Single column, full-width |
| Tablet | 640px - 1024px | Collapsible overlay | Centered, max 720px |
| Desktop | > 1024px | Fixed 260px | Centered, max 900px |
### 5.2 Mobile Adaptations
- Hamburger menu → slide-out sidebar
- Code blocks: horizontal scroll (no wrapping)
- Tables: horizontal scroll with shadow indicators
- Try It panel: full-screen modal on mobile
- Search: full-screen modal
- Endpoint cards: stacked layout
### 5.3 Tablet Adaptations
- Sidebar: collapsible overlay (not fixed)
- Content: 720px max-width
- TOC (table of contents): hidden, moved to sidebar
---
## 6. Accessibility
- WCAG 2.1 AA compliance target
- Keyboard navigation for all interactive elements
- Focus indicators: 2px solid `var(--accent)` offset 2px
- Skip to main content link
- ARIA labels on icon-only buttons
- Color contrast ratio ≥ 4.5:1 for text
- Reduced motion: respect `prefers-reduced-motion`
- Screen reader: announce page changes and search results
---
## 7. Performance
- Target: Lighthouse score ≥ 90 for all metrics
- Code splitting by route
- Lazy load below-fold content
- Search index: client-side with Web Worker
- Dark mode: CSS variables only (no JS re-render)
- Fonts: subset + display=swap
- Images: WebP with fallback
---
## 8. Implementation Notes
### 8.1 Suggested Stack
- **Framework**: Next.js 14 (App Router) or Astro
- **Styling**: Tailwind CSS + CSS variables for theming
- **MDX**: For interactive doc content
- **Search**: Algolia DocSearch or local FlexSearch
- **Code Highlighting**: Shiki (server-side, VS Code themes)
- **Deployment**: Vercel or Cloudflare Pages
### 8.2 OpenAPI Integration
The site should auto-generate reference docs from `openapi.yaml`:
- Endpoint list from paths
- Parameter tables from schema
- Response schemas from components
- Try It from API endpoint + API key stored in localStorage
### 8.3 Versioning Strategy
- Current stable: v1 (shown by default)
- v2 available via version picker
- Old versions accessible but marked deprecated
- Changelog linked from version picker
---
*Design specification created for BUY-2074. For implementation, create subtasks for: IA setup, component library, page templates, dark mode, search, responsive layout, and OpenAPI integration.*