One backend, many doors

Case’s app and Molly’s browser have been talking to the same Traversal all morning, and neither knows the other exists. Different doors, Act 0 said, and left it at that. It is time to say what a door actually is.

The menu on the wall

The backend publishes a list of askable things, and the list is an APIConcept · lights on your mapAPIApplication Programming Interface: a defined way for one piece of software to request information or capabilities from another, like a restaurant’s menu of what can be ordered. The asker uses the interface and never sees the kitchen.. Not a machine, not a place. A published list of askable things. The app orders off it, the browser orders off it, and neither has ever seen the kitchen, which is the entire point of having a menu.

Each item on the menu is an API endpointConcept · lights on your mapAPI endpointOne specific capability exposed through an API, commonly named by an HTTP method plus a path: POST /register, GET /results. The path says which thing, the method says what kind of ask.. Case’s morning has mostly been one of them: POST /register, the endpoint this whole act has been travelling toward and through.

And the menu’s organising habit, resources as paths, the standard methods doing the acting, has a name of its own: RESTConcept · lights on your mapRESTA common architectural style for organising web APIs: resources live at paths like /entries/11208, and the standard HTTP methods act on them. The predictability is the point. An engineer can guess an unfamiliar REST API’s shape and be roughly right.. Traversal’s API is RESTful, which mostly means a stranger could guess where things live and be right often enough to be dangerous.

Not everything speaks JSON

A sidebar, and a look forward. On race day, months from this morning, a feed will arrive from the timing vendor speaking XMLRecognition — just know it existsXMLAn older structured text format using tags instead of braces and brackets. It ran the world before JSON and still runs a lot of banking, government, and enterprise systems., an older handwriting with tags instead of braces. The race director’s results export will leave as CSVRecognition — just know it existsCSVComma-Separated Values: a table as plain text lines, a header row then one row per record. The format of spreadsheet exports everywhere., a spreadsheet flattened into lines. Reading a format and finding its structure is parsingRecognition — just know it existsparsingReading text in some format and identifying its structure so a program can work with it. When it fails, the error says failed to parse, and it means the text was malformed.; packing a structure into text for the trip is serializationRecognition — just know it existsserializationConverting an internal data structure into a transferable format, such as an object becoming JSON text. The outbound half of an exchange. and unpacking on arrival is deserializationRecognition — just know it existsdeserializationConverting the transferable format back into a live structure, such as JSON text becoming an object again. The inbound half.. Every exchange this morning did both without being asked.

One more name to file away: GraphQLRecognition — just know it existsGraphQLAn API approach where the client sends a query naming exactly the fields it wants back, as an alternative to REST’s fixed endpoints. More client control, its own new complexity.. At a design review last spring somebody asked whether the new spectator API should use it, and the room had opinions for an hour. Recognise the word; the argument can wait.

Doors, named. Next: who besides Case has been knocking on them all morning.