API servicemedium

Inventory reservations with safe retries

Build an inventory reservation feature, then add idempotent retries and cancellation while preserving stock invariants.

Suggested effort
~3h focused work
Window
24 hours
Starts from
An empty repo
Stack
Requires SQLite
Sign in to start this build →

Opens in a new tab. The clock starts when you press Start inside the environment, not before, and your workspace is kept while you step away.

Time window 24 hours. Suggested effort about 3 hours.

Context

A small shop has a working product catalogue. Customers can see stock, but there is no way to reserve it during checkout. Build the reservation feature, then adapt it to cancellation and retrying clients. This is an original PraxisAI exercise for the Shopify practice path, not a Shopify question or live pairing interview. All stages are visible up front.

Stage 1: establish the contract

Before asking the agent to implement it, write a short design note in README.md: the stock invariant, the transaction boundary and the response format.

  • Seed SKUs notebook with 5 units and pen with 10 units on first startup.
  • GET /products lists SKU, total stock, reserved stock and available stock.
  • POST /reservations accepts request_id, sku and integer quantity. Return 201 with an opaque reservation ID and its status active.
  • A successful reservation reduces available stock, not total stock. Insufficient stock returns 409 without changing anything. An unknown SKU returns 404.
  • Empty request IDs, non-integer or non-positive quantities return 400. Booleans are not valid integers in this API. Errors have a consistent JSON body.
  • Persist stock, reservations and request IDs in SQLite. Restarting the service must preserve their state without reseeding over changed data.

Stage 2: handle a changed requirement

A checkout client retries after losing its connection. The same logical request must never reserve twice.

  • Repeating a successful request_id with the same SKU and quantity returns 200 with the original reservation and its current status, without changing stock.
  • Reusing that ID with different inputs returns 409, including after cancellation.
  • DELETE /reservations/:id cancels an active reservation and releases its units. It returns 200 with status cancelled; repeating cancellation is a successful no-op. Unknown reservation IDs return 404.
  • Retrying the original POST after cancellation returns the cancelled reservation; it does not reactivate it. A new reservation needs a new request ID.
  • Failed requests do not claim a request ID. An insufficient-stock request may succeed on a later retry after stock has been released.

Acceptance criteria

  • Reserving 3 notebooks leaves 2 available. Retrying the same successful request leaves 2 available. Asking for 3 more returns 409 and still leaves 2 available.
  • Cancelling the first reservation restores 5 available. Repeating cancellation still leaves 5. Retrying its original request returns cancelled and leaves 5.
  • Two concurrent distinct requests for 4 notebooks cannot both succeed. Exactly one succeeds and available stock is 1; no observer can see negative stock.
  • Two concurrent copies of the same valid request produce one reservation, one logical stock change and the same reservation ID in both responses.
  • available = total - sum(active quantities) always holds. Invalid input and conflicts leave the persisted state unchanged.
  • Add automated domain tests plus at least one real HTTP round trip. Cover concurrency, restart persistence, duplicate IDs, cancellation and malformed input.

Constraints and handoff

Use any server language with SQLite. Suggested: Python with FastAPI or Flask, Node with Fastify, or Go. Keep stock logic separate from HTTP handling. No payment provider, authentication, external service, background expiry or frontend is required. Document the chosen port and one run command. Put the runnable test command in README.md and include an AI-use note explaining one generated change you checked or corrected. The standard PraxisAI project rubric applies.

Deliverables (every project)

  • Source code committed in this repository (the grader diffs against the first commit).
  • README.md that replaces the stub, with: how to install, run and test it (copy-pasteable commands); the decisions and trade-offs you made; what you would do next with more time; and a short note on how you used the AI agent (what you delegated, what you checked or rewrote).
  • Automated tests that run with a single command (npm test, pytest, go test ./... or cargo test).
  • No secrets in the repository. Anything configurable reads from environment variables with safe defaults.

Ground rules

  • The 24-hour clock is a window, not a workload. Stop at roughly the suggested effort, then write down what you would do next. A small, finished, tested core beats a large unfinished one.
  • Use the AI agent as much or as little as you like: every prompt is recorded and the report shows how it was used. You are judged on the result and on whether you understood and verified what the agent produced.
  • The work is yours. PraxisAI uses it only to produce your assessment report.