OpenAPI: REST API CRUD Products Endpoint
Document a products API with GET, POST, PUT, DELETE operations. Includes price fields, category filtering, inventory status, and image URLs in the schema.
Detailed Explanation
Defining a Products CRUD API
An e-commerce products API extends the basic CRUD pattern with domain-specific fields and filtering capabilities.
Product Schema
components:
schemas:
Product:
type: object
required:
- id
- name
- price
properties:
id:
type: string
description: Unique product identifier
name:
type: string
description: Product display name
price:
type: number
description: Price in USD
category:
type: string
description: Product category
inStock:
type: boolean
description: Whether the product is currently in stock
imageUrl:
type: string
description: URL of the product image
Filtering Parameters
Products APIs typically support filtering by category, price range, and stock status:
parameters:
- name: category
in: query
schema:
type: string
description: Filter by category name
- name: minPrice
in: query
schema:
type: number
description: Minimum price filter
- name: maxPrice
in: query
schema:
type: number
description: Maximum price filter
- name: inStock
in: query
schema:
type: boolean
description: Filter by stock availability
Price Handling
Use type: number (not integer) for prices since they include decimal values. In practice, many APIs transmit prices in the smallest currency unit (cents) as integers to avoid floating-point issues. Document your choice in the field description.
Image Uploads
For product images, define a separate POST /products/{id}/images endpoint with multipart/form-data content type rather than including image uploads in the main CRUD operations.
Use Case
Building an e-commerce API or product catalog service where you need to document product listing, creation, price management, and inventory tracking endpoints for frontend developers or third-party integrations.