{"openapi":"3.1.0","info":{"title":"BookNest Testing API","version":"1.0.0","description":"A fictional, synthetic bookstore API for UI, API, negative, concurrency, and resilience testing. It is demonstration software, does not process real sales or payments, and is not affiliated with any similarly named company, product, or service."},"externalDocs":{"description":"BookNest product requirements and automation context","url":"https://booknest-testing.com/booknest-requirements.md"},"x-legal-notice":"All books, authors, identifiers, users, prices, payments, orders, and responses are synthetic. Use synthetic test data only.","servers":[{"url":"https://booknest-testing.com/api/v1","description":"Current BookNest environment"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"testAdminKey":{"type":"apiKey","in":"header","name":"X-Test-Admin-Key"}},"parameters":{"testRunId":{"name":"X-Test-Run-Id","in":"header","required":false,"schema":{"type":"string","default":"shared-demo"},"description":"Isolates all state for one automated execution."},"clientId":{"name":"X-Client-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Identifies an anonymous cart before login."},"testDefects":{"name":"X-Test-Defects","in":"header","required":false,"schema":{"type":"string","example":"api,state"},"description":"Comma-separated intentional defect packs: smoke, ui, functional, validation, api, state. The defects query parameter is equivalent."}}},"paths":{"/health":{"get":{"summary":"Service health","responses":{"200":{"description":"Healthy"}}}},"/books":{"get":{"summary":"Search and filter books","parameters":[{"$ref":"#/components/parameters/testRunId"},{"name":"query","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"pageSize","in":"query","schema":{"type":"integer","maximum":100}}],"responses":{"200":{"description":"Paginated catalogue"},"429":{"description":"Rate limited"},"503":{"description":"Service unavailable"}}}},"/books/{id}":{"get":{"summary":"Book details","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Book"},"404":{"description":"Not found"}}}},"/auth/register":{"post":{"summary":"Register a synthetic customer","responses":{"201":{"description":"Registered"},"409":{"description":"Duplicate email"},"422":{"description":"Validation error"}}}},"/auth/login":{"post":{"summary":"Create a one-hour demo bearer session and merge the anonymous cart","responses":{"200":{"description":"Authenticated"},"401":{"description":"Invalid credentials"}}}},"/auth/logout":{"post":{"summary":"Invalidate a bearer session","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Signed out"}}}},"/cart":{"get":{"summary":"Read a cart","responses":{"200":{"description":"Cart"}}},"post":{"summary":"Add a book","responses":{"201":{"description":"Added"},"409":{"description":"Stock conflict"}}},"patch":{"summary":"Set quantity","responses":{"200":{"description":"Updated"}}},"delete":{"summary":"Remove one or all cart items","responses":{"200":{"description":"Updated"}}}},"/promotions/validate":{"post":{"summary":"Validate and apply BOOK10","responses":{"200":{"description":"Applied"},"422":{"description":"Expired or unknown"}}}},"/orders":{"get":{"summary":"List authenticated customer orders","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Orders"}}},"post":{"summary":"Place an idempotent simulated order","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"responses":{"201":{"description":"Created"},"409":{"description":"Inventory or price conflict"},"422":{"description":"Payment or validation failure"}}}},"/orders/{id}/cancel":{"post":{"summary":"Cancel an order and restore inventory","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Cancelled"},"404":{"description":"Not found"}}}},"/test/defects":{"get":{"summary":"Discover intentional defect packs","description":"Public, stateless catalogue of supported packs, defect IDs, expected behavior, defective behavior, and activation examples.","parameters":[{"$ref":"#/components/parameters/testDefects"},{"name":"defects","in":"query","required":false,"schema":{"type":"string","example":"smoke,ui"}}],"responses":{"200":{"description":"Defect catalogue and active request packs"}}}},"/test/scenario":{"get":{"summary":"Read the active scenario","security":[{"testAdminKey":[]}],"responses":{"200":{"description":"Scenario"},"403":{"description":"Invalid key"}}},"post":{"summary":"Activate a deterministic scenario","security":[{"testAdminKey":[]}],"responses":{"200":{"description":"Activated"},"422":{"description":"Unsupported scenario"}}}},"/test/reset":{"post":{"summary":"Reset one isolated test run","security":[{"testAdminKey":[]}],"responses":{"200":{"description":"Reset"},"403":{"description":"Invalid key"}}}}}}