GraphQL API Documentation

Alternative API with powerful querying capabilities

Endpoint: /api/graphql
Queries: 11
Mutations: 9

🚀 Quick Start

1. 🔐 Get API Key Token

curl -X POST http://localhost:3000/api/auth/login   -H "Content-Type: application/json"   -d '{"email":"user@example.com","password":"password123"}'

2. 🧪 Open GraphQL Playground

Open Playground

3. 🧾 Add Token in HTTP Headers

{
  "Authorization": "Bearer <your_token_here>"
}

4. ▶️ Try Your First Query

query {
  me {
    id
    email
  }
}

✨ Why GraphQL

  • Request exactly the data you need
  • Combine multiple queries in one request
  • Strongly typed schema
  • Better performance by reducing over fetching

📝 Notes

  • All operations require Authorization header using Bearer token
  • Use session_token (JWT) or api_token from /api/auth/login as the Bearer token
  • IDs are commonly strings in GraphQL, but some fields expect Int in variables, follow each example
  • Most queries and mutations validate ownership by user_id
  • Password reset (forgotPassword) is rate limited to 3 attempts per 30 minutes
  • QA tip: set AUTH_RATE_LIMIT_MULTIPLIER (e.g., 2) to relax auth throttling without disabling it
  • Products: Custom image paths are not allowed. All products use the default image path (images/custom.jpg)
  • Categories: Allowed values are Electronics, Accessories, Office, Furniture, Sample
  • Hard Deletes (Cleanup): DELETE /api/orders/:id hard-deletes an order and restores stock.
  • Hard Deletes (Cleanup): DELETE /api/products/:id?force=true cascades and deletes related orders (no stock restore).
  • Cleanup Visibility: DELETE /api/products/:id returns order IDs blocking deletion (409) and order IDs deleted when force=true.
  • Malformed JSON: REST endpoints return HTTP 400 with { success: false, error: 'Malformed JSON payload' } when the body is not valid JSON.

🔐 Product Permission System

Products have permission levels that control what operations are allowed:

PermissionReadUpdateDeleteNotes
ALL✓✓✓Full CRUD - user-created products
N_DELETE✓✓✗Template products - cannot be deleted
READ_ONLY✓✗✗Future use
  • Template Products: When a user registers, they receive 10 template products with N_DELETE permission. These can be updated but NOT deleted.
  • User Products: Products created via createProduct have ALL permission and can be fully managed.
  • Image Restriction: image_url cannot be modified for ANY product (returns error if attempted).