Sandboxes and Test Modes

Jonas's onboarding email had two keys in it, and Vera only ever used one. The second begins tnd_test_ and comes with a single line of explanation: use this while you are learning. It is easy to skim past, and it is the most generous thing in the message, because it is permission to be wrong at no cost.

A sandbox — also called test mode — is a separate copy of the API that runs on made-up data and has no effect on anything real. Same addresses, same parameters, same errors; different universe. It works like a flight simulator: real controls, real procedures, fake sky. Crashing costs nothing, which is exactly why first landings happen there and not over a city.

What a Sandbox Actually Is

Behind the test key sits a second running copy of Tandem's API with its own store of invented data: test stations at invented addresses, a fleet of bikes nobody pedals, rides that never happened. Ask it for station st_014 and you get an object of the same shape as the real one, filled with numbers that mean nothing to anybody.

This is where Chapter 3's reservation lived. When you sent that POST and reserved bike bk_0977, no rider in Riverport lost a bike, which is why the book could cheerfully suggest running it twice to see what a duplicate looks like. The lesson was real. The reservation was not. (Chapter 3 skipped the key on that one call — Tandem leaves the sandbox's reservation door unlocked precisely so first contact needs no paperwork; everything else about the sandbox checks the same credentials the live counter would.)

The Tells

Providers want you to know which side you are on, so they mark it, usually in more than one way. The clearest mark is the key prefix: tnd_test_ against tnd_live_, visible in the command before you press Enter. Tandem does this too: its sandbox answers at sandbox.api.tandem.example, so the universe is named in the URL itself as well as in the key.

Some responses carry the mark too, as a field saying the object is a test object, or a banner across the provider's own dashboard when you are viewing test data. Whatever the markers are for a given API, the documentation states them, and finding that paragraph is a worthwhile first stop on any new provider's site.

What a Sandbox Is For, and What It Cannot Prove

Three uses cover almost everything. First requests against an API you have never touched, where being wrong four times in a row is the normal path. Trying the verbs that change things, where a mistake against live data would be expensive. And demonstrations or training, where you would rather not explain to a colleague why the screen now shows a real reservation.

The limits deserve equal billing, because false confidence is its own kind of incident. Sandbox data is tidy, small, and calm. It has no rush hour, no half-finished records, no stations that were renamed three years ago and still carry the old spelling. Working in the sandbox proves the mechanics of your request; it proves nothing about how that request behaves against the volume and mess of the real thing, which is the entire subject of Chapters 7 and 8.

The Switching Discipline

Between test and live, almost nothing changes: the key, and — on Tandem and many other APIs — the hostname alongside it. Everything else about the command stays identical, which is the design working as intended and also the trap, because two commands that differ by one short word are easy to confuse.

The classic incident writes itself. Somebody rehearses in the sandbox, gets pulled into a meeting, comes back, presses the up arrow one line too far, and re-runs the live command from before the rehearsal. There is a two-second habit that prevents it entirely: read the prefix in your own command before you commit to it. That check costs nothing and has stopped more small disasters than any policy document.

curl -H "Authorization: Bearer tnd_test_..." \
  https://sandbox.api.tandem.example/v1/stations/st_014

curl -H "Authorization: Bearer tnd_live_..." \
  https://api.tandem.example/v1/stations/st_014