Sending Data: Your First POST

Everything you have sent so far only looked. This page changes something. Tandem's partner sandbox — a practice copy of the API where nothing is real, formally introduced in Chapter 6 — lets anyone try reserving a bike. You are going to reserve bk_0977 at Old Market, by hand, and when the response comes back, something will exist that did not exist a minute ago, because you asked in the right shape.

curl -i -X POST https://sandbox.api.tandem.example/v1/reservations \
  -H "Content-Type: application/json" \
  -d '{"bike_id": "bk_0977", "station_id": "st_014"}'

Read it piece by piece, because all three new flags from the curl page just arrived at once. -X POST says the verb out loud — strictly, -d alone already makes the request a POST, but stating it costs nothing and reads clearly. What -d does not do is set the format label: its default is an old form format, which is why the Content-Type header is not optional. -d attaches the body — the cargo, written as JSON. And -H "Content-Type: application/json" is the label on the parcel, announcing the format so the server knows how to read it. The -i is last page's flag, here so the verdict prints with the receipt, and the backslashes at the line ends just split one long command across lines for readability. One honest note for Windows readers: multi-line examples like this one are written for the macOS and Linux shell; the calm Windows route is Git Bash (it installs with Git) or WSL, where they run as printed — in PowerShell the quoting rules differ enough to mangle the JSON.

The Body Comes from the Docs, Not from Guessing

Where did bike_id and station_id come from? The documentation. The reference page for POST /reservations names the required fields, their types, and what comes back on success — the same menu principle as the last page, now applied to cargo. Building a body is an act of reading, not invention: the docs say what the form wants, and you fill exactly that in. One deliberate simplification on this page: the sandbox's reservation door is open, no key needed. The real one is locked, and Chapter 5 is where you get the key.

Reading the Receipt

HTTP/1.1 201 Created
Content-Type: application/json

{"id": "res_3f81", "bike_id": "bk_0977", "station_id": "st_014",
 "expires_at": "2026-08-21T10:32:00Z", "status": "active"}

The verdict is 201 Created — Chapter 2's specific success: a new thing now exists. And the body is its receipt: the reservation's own id, res_3f81, and when it expires. Keep the habit this teaches: when a POST succeeds, note the id it returns. That id is the name of the thing you made — the way you will ask about it, change it, or cancel it later. "It worked" is a feeling; "res_3f81 exists" is a fact.

Now Respect the Verb

One more thing before the chapter closes, and it is the lesson this sandbox exists to make cheap. Press the up arrow in your terminal — it recalls the last command — and run the same POST again. Verdict: 201 Created. A second reservation, res_3f82, now also exists. Nothing warned you, nothing deduplicated. POST creates; twice creates twice — Chapter 2's warning, now demonstrated on your own screen where it costs nothing. In Chapter 7 this exact moment returns with money on the table, and you will be ready for it.