Doors, catalogued

Three boroughs away, the thing the race director wanted to check turns out to be the entry count. At 10:01 the organizer portal comes up with the number already climbing, and the director settles in to watch — having walked, without knowing it, through a different kind of door than Case did.

Traversal’s doors sort into three kinds, and the sorting has nothing to do with technology. The question is who may knock.

Three audiences

The doors Case’s app has used all morning belong to an internal APIConcept · lights on your mapinternal APIAn API meant for systems within the same organisation: the frontend talking to its own backend, dashboards talking to services. The technology matches an external API; the audience, and how carefully change must be managed, is what differs.: Traversal’s own software talking to Traversal’s own backend. If it must change next week, Traversal changes both sides itself and nobody outside ever knows.

The organizer portal rides an external APIConcept · lights on your mapexternal APIAn API offered to people outside the organisation: partners, customers, developers. The same technology as an internal one, and changes must be managed far more carefully. Strangers have built on the promises., offered to race organisations that are customers, and changing one of those is a diplomatic event. Strangers built on its promises, and strangers have long memories.

And when Traversal itself knocks on Ledgerline’s door this morning, that same door, seen from Traversal’s side, is a third-party APIConcept · lights on your mapthird-party APIAn API operated by another organisation that your product depends on. The provider calls it their external API; you experience the same interface as a dependency you do not control.. One interface, two names, depending on which side of it you stand.

The promises in writing

What keeps all this knocking orderly is that every door publishes its rules. The formal shape, which fields, which types, which answers, is the API contractConcept · lights on your mapAPI contractThe defined agreement for how clients and an API communicate: endpoints, methods, required fields, types, promised responses, and errors. Teams build independently against it, and breaking it breaks them.. The human explanation of that shape, with examples a person can actually follow, is the API documentationConcept · lights on your mapAPI documentationThe readable explanation of how to use an API: endpoints, example requests and responses, authentication, errors, limits. The contract turned into something a person can implement from., and engineers judge a company by it the way cooks judge a kitchen by its knives.

Contracts still need to change, and the escape hatch is API versioningConcept · lights on your mapAPI versioningLetting several versions of an API contract exist at once, commonly /v1/ and /v2/ in the path, so the API can evolve without every client changing on the same day. Old versions get deprecated, which starts a long, polite migration.. Traversal’s organizer API is on v2. One small race, run by a volunteer with strong opinions and a spreadsheet, still calls v1, which was deprecated a year ago and will be turned off after this season. Somebody at Traversal owns that conversation, and it is going slowly.

Doors, sorted; promises, written down. What none of this yet explains is how any door knows who is knocking, and that question is the next scene entirely.