{ "openapi": "3.0.3", "info": { "title": "E-commerce API Demo", "version": "1.0.0", "description": "Original PHP sandbox with fictional catalog data. Browser cookies isolate stock, carts and orders. No payments or external business systems." }, "servers": [ { "url": "/api/demo/v1" } ], "paths": { "/products": { "get": { "summary": "List, filter and sort products", "operationId": "get_products", "responses": { "200": { "description": "Successful response (also idempotent replay or merge)", "headers": { "X-CSRF-Token": { "schema": { "type": "string" }, "description": "Session CSRF token; retain for mutations" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Products" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid origin or CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stock, empty-cart, order limit or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 8 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Wrong content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Input validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or sandbox capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary storage failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "description": "Positive page number (1\u2013100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "per_page", "in": "query", "description": "Items per page (1\u201312, default 6).", "schema": { "type": "integer", "minimum": 1, "maximum": 12 } }, { "name": "q", "in": "query", "description": "Search name and description, up to 80 characters.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "accessories, electronics or workspace.", "schema": { "type": "string" } }, { "name": "in_stock", "in": "query", "description": "true or false.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "name_asc, price_asc or price_desc.", "schema": { "type": "string" } } ] } }, "/products/{id}": { "get": { "summary": "Get a product and its offers", "operationId": "get_products_id", "responses": { "200": { "description": "Successful response (also idempotent replay or merge)", "headers": { "X-CSRF-Token": { "schema": { "type": "string" }, "description": "Session CSRF token; retain for mutations" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductResponse" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid origin or CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stock, empty-cart, order limit or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 8 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Wrong content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Input validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or sandbox capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary storage failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ] } }, "/cart": { "get": { "summary": "Get your current cart and CSRF header", "operationId": "get_cart", "responses": { "200": { "description": "Successful response (also idempotent replay or merge)", "headers": { "X-CSRF-Token": { "schema": { "type": "string" }, "description": "Session CSRF token; retain for mutations" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid origin or CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stock, empty-cart, order limit or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 8 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Wrong content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Input validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or sandbox capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary storage failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [] } }, "/cart/items": { "post": { "summary": "Add an offer or merge its quantity", "operationId": "post_cart_items", "responses": { "200": { "description": "Successful response (also idempotent replay or merge)", "headers": { "X-CSRF-Token": { "schema": { "type": "string" }, "description": "Session CSRF token; retain for mutations" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid origin or CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stock, empty-cart, order limit or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 8 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Wrong content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Input validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or sandbox capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary storage failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "security": [ { "csrf": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id", "variant_id", "quantity" ], "additionalProperties": false, "properties": { "product_id": { "type": "integer", "minimum": 1, "maximum": 100000 }, "variant_id": { "type": "integer", "minimum": 1, "maximum": 100000 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 20 } } } } } } } }, "/cart/items/{id}": { "patch": { "summary": "Set an existing cart item\u2019s quantity", "operationId": "patch_cart_items_id", "responses": { "200": { "description": "Successful response (also idempotent replay or merge)", "headers": { "X-CSRF-Token": { "schema": { "type": "string" }, "description": "Session CSRF token; retain for mutations" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid origin or CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stock, empty-cart, order limit or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 8 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Wrong content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Input validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or sandbox capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary storage failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "security": [ { "csrf": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "quantity" ], "additionalProperties": false, "properties": { "quantity": { "type": "integer", "minimum": 1, "maximum": 20 } } } } } } }, "delete": { "summary": "Remove an existing cart item", "operationId": "delete_cart_items_id", "responses": { "200": { "description": "Successful response (also idempotent replay or merge)", "headers": { "X-CSRF-Token": { "schema": { "type": "string" }, "description": "Session CSRF token; retain for mutations" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid origin or CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stock, empty-cart, order limit or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 8 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Wrong content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Input validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or sandbox capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary storage failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "security": [ { "csrf": [] } ] } }, "/orders": { "post": { "summary": "Create an isolated demo order", "operationId": "post_orders", "responses": { "200": { "description": "Successful response (also idempotent replay or merge)", "headers": { "X-CSRF-Token": { "schema": { "type": "string" }, "description": "Session CSRF token; retain for mutations" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid origin or CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stock, empty-cart, order limit or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 8 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Wrong content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Input validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or sandbox capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary storage failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{8,80}$" } } ], "security": [ { "csrf": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "delivery_method", "demo_acknowledged" ], "additionalProperties": false, "properties": { "delivery_method": { "type": "string", "enum": [ "demo_pickup", "demo_shipping" ] }, "demo_acknowledged": { "type": "boolean", "enum": [ true ] } } } } } } } }, "/orders/{id}": { "get": { "summary": "Get an order from your sandbox", "operationId": "get_orders_id", "responses": { "200": { "description": "Successful response (also idempotent replay or merge)", "headers": { "X-CSRF-Token": { "schema": { "type": "string" }, "description": "Session CSRF token; retain for mutations" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid origin or CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stock, empty-cart, order limit or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 8 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Wrong content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Input validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or sandbox capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary storage failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ] } }, "/reset": { "post": { "summary": "Restore your stock, cart and orders", "operationId": "post_reset", "responses": { "200": { "description": "Successful response (also idempotent replay or merge)", "headers": { "X-CSRF-Token": { "schema": { "type": "string" }, "description": "Session CSRF token; retain for mutations" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetResponse" } } } }, "400": { "description": "Malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Invalid origin or CSRF token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Missing resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Wrong method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stock, empty-cart, order limit or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 8 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Wrong content type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Input validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or sandbox capacity limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary storage failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [], "security": [ { "csrf": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "additionalProperties": false, "properties": {} } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } }, "Variant": { "type": "object", "required": [ "id", "label", "sku", "price_cents", "stock" ], "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "sku": { "type": "string" }, "price_cents": { "type": "integer", "minimum": 0 }, "stock": { "type": "integer", "minimum": 0 } } }, "Product": { "type": "object", "required": [ "id", "name", "category", "description", "image", "currency", "variants", "price_from_cents", "total_stock" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "accessories", "electronics", "workspace" ] }, "description": { "type": "string" }, "image": { "type": "string" }, "currency": { "type": "string", "enum": [ "USD" ] }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } }, "price_from_cents": { "type": "integer" }, "total_stock": { "type": "integer" } } }, "CartItem": { "type": "object", "required": [ "id", "product_id", "variant_id", "quantity", "product_name", "variant_label", "unit_price_cents", "subtotal_cents", "available_stock" ], "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "variant_id": { "type": "integer" }, "quantity": { "type": "integer" }, "product_name": { "type": "string" }, "variant_label": { "type": "string" }, "unit_price_cents": { "type": "integer" }, "subtotal_cents": { "type": "integer" }, "available_stock": { "type": "integer" } } }, "Cart": { "type": "object", "required": [ "items", "quantity", "total_cents", "currency" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItem" } }, "quantity": { "type": "integer" }, "total_cents": { "type": "integer" }, "currency": { "type": "string", "enum": [ "USD" ] } } }, "Order": { "type": "object", "required": [ "id", "reference", "status", "delivery_method", "currency", "total_cents", "items", "created_at", "demo_only" ], "properties": { "id": { "type": "integer" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "demo_created" ] }, "delivery_method": { "type": "string", "enum": [ "demo_pickup", "demo_shipping" ] }, "currency": { "type": "string", "enum": [ "USD" ] }, "total_cents": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItem" } }, "created_at": { "type": "string", "format": "date-time" }, "demo_only": { "type": "boolean", "enum": [ true ] } } }, "Products": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "type": "object", "required": [ "page", "per_page", "total", "total_pages", "sort" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "sort": { "type": "string" } } } } }, "ProductResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Product" } } }, "CartResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "cart" ], "properties": { "cart": { "$ref": "#/components/schemas/Cart" } } } } }, "OrderResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/Order" }, "replayed": { "type": "boolean" } } } } }, "ResetResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "reset", "cart" ], "properties": { "reset": { "type": "boolean" }, "cart": { "$ref": "#/components/schemas/Cart" } } } } } }, "securitySchemes": { "csrf": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "Read from any API response header, normally GET /cart. Same-origin session cookie is also required." } } } }