Overview
The Products API provides endpoints for browsing, searching, and creating products in the ShopStack catalog.
GET /api/products
Retrieve a paginated list of products.
Request
Method: GET
Path: /api/products
Authentication: None required
Query Parameters:
Page number for pagination
Number of products per page
Filter products by category
Response
Array of product objectsProduct’s unique identifier
Total number of products matching the query
Example
curl -X GET "http://localhost:5000/api/products?page=1&per_page=10&category=electronics"
{
"products": [
{
"id": 1,
"name": "Laptop Pro 15",
"description": "High-performance laptop with 15-inch display",
"price": 1299.99,
"stock": 25,
"category": "electronics",
"created_at": "2024-01-10T08:00:00",
"updated_at": "2024-01-15T12:30:00"
},
{
"id": 2,
"name": "Wireless Mouse",
"description": "Ergonomic wireless mouse",
"price": 29.99,
"stock": 150,
"category": "electronics",
"created_at": "2024-01-10T08:15:00",
"updated_at": "2024-01-10T08:15:00"
}
],
"total": 45,
"page": 1,
"per_page": 10,
"pages": 5
}
GET /api/products/<id>
Retrieve a specific product by ID.
Request
Method: GET
Path: /api/products/<id>
Authentication: None required
Path Parameters:
Response
Product object with all details (same structure as products array above)
Example
curl -X GET http://localhost:5000/api/products/1
{
"product": {
"id": 1,
"name": "Laptop Pro 15",
"description": "High-performance laptop with 15-inch display",
"price": 1299.99,
"stock": 25,
"category": "electronics",
"created_at": "2024-01-10T08:00:00",
"updated_at": "2024-01-15T12:30:00"
}
}
Error Responses
404 Not Found - Product not found:
{
"error": "Product not found"
}
GET /api/products/search
Search for products by name or description.
Request
Method: GET
Path: /api/products/search
Authentication: None required
Query Parameters:
Search query string. Searches in product name and description.
Response
Array of matching product objectsProduct’s unique identifier
Example
curl -X GET "http://localhost:5000/api/products/search?q=laptop"
{
"products": [
{
"id": 1,
"name": "Laptop Pro 15",
"description": "High-performance laptop with 15-inch display",
"price": 1299.99,
"stock": 25,
"category": "electronics"
},
{
"id": 5,
"name": "Laptop Stand",
"description": "Adjustable laptop stand for ergonomic setup",
"price": 49.99,
"stock": 80,
"category": "accessories"
}
],
"count": 2
}
Error Responses
400 Bad Request - Missing search query:
{
"error": "Search query parameter 'q' is required"
}
POST /api/products
Create a new product.
Request
Method: POST
Path: /api/products
Authentication: JWT token required
Headers:
Authorization: Bearer <access_token>Content-Type: application/json
Body Parameters:
Response
Created product object with all details
Example
curl -X POST http://localhost:5000/api/products \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
"name": "Mechanical Keyboard",
"description": "RGB mechanical gaming keyboard",
"price": 89.99,
"stock": 50,
"category": "electronics"
}'
{
"product": {
"id": 10,
"name": "Mechanical Keyboard",
"description": "RGB mechanical gaming keyboard",
"price": 89.99,
"stock": 50,
"category": "electronics",
"created_at": "2024-01-15T14:20:00",
"updated_at": "2024-01-15T14:20:00"
}
}
Error Responses
400 Bad Request - Missing required field:
{
"error": "Missing required field: name"
}
{
"msg": "Missing Authorization Header"
}