Meet Tandem

From here to the last chapter, one product carries every example in this book: Tandem, the bike-share of the city of Riverport. Two hundred and fourteen stations, thousands of rides a day, an app riders like, and — the reason it is in this book — a public partner API at api.tandem.example. This page is the cast list. Meet everyone once, properly, and every later page lands on ground you already know.

You have already met Vera in passing. She coordinates mobility at Riverport's city transport office, and every Thursday she assembles the same report: which Tandem stations run empty in the morning, which ones overflow in the evening. Today she builds it by tapping through the app, station by station, copying numbers into a spreadsheet by hand. This book is the story of that report learning to fill itself.

Riverport and Its Bikes

Riverport is mid-sized and bike-friendly, and Tandem is how much of it moves. In the morning the bikes flow like a tide toward the center; every evening they flow back out. Old Market station — you will get to know it by its code, st_014 — fills and empties twice a day, as reliably as weather. The point of all this detail: the data is alive. It changes every minute, which is exactly what makes an API worth having, and worth learning on.

The Thursday Report

Vera's report answers two questions for the city: where do riders find empty docks, and where do they find no bikes at all? The city uses it to nudge Tandem's rebalancing crews and to plan new stations. Assembling it takes her most of Thursday morning — two hundred and fourteen stations is a lot of tapping — and last month a typo in row 40 sent a rebalancing crew to the wrong end of town. Painful, error-prone, and about to become a handful of well-aimed requests.

The Partner API

Tandem publishes its API for exactly people like Vera — cities, tourism boards, researchers, partners. The documentation is public. The counter offers four things, called resources — the nouns an API serves: stations (where they are, how many bikes and free docks right now), bikes (each one's status), rides (trips, start to finish), and riders (a rider's own profile and history — locked, for reasons Chapter 5 will make satisfying). Acting on those nouns gets doors of its own — Chapter 3 will reserve a bike through one — but these four are the data the counter serves. Partners get access by asking; a support engineer named Jonas answers the emails. You will be reading his replies throughout this book, because "ask the provider" is a real skill and Jonas is how it looks in practice.

The Road Ahead

Here is how the book uses this world. Chapters 2 through 4 learn the language: what a request looks like, how to send one, how to read the answer. Chapters 5 and 6 get through the door properly: keys, and the documentation that tells you what to ask. Chapters 7 through 9 survive reality: errors, limits, big data, and news that arrives on its own. Each chapter moves the Thursday report one concrete step closer to pulling itself. The examples accumulate — same stations, same codes, same rush hour — so by Chapter 8, "two hundred and fourteen stations" will need no reintroduction.