Service catalog · 04 of 05 · Discovery

From an interview to an API

The quotes are illustrative; everything on the right is real in Airframe. Each one started as a sentence like these, even when the person saying it was me.

From an interview to an API Four columns: what we heard, the job to be done, the noun, and the API. Four example rows. "Three weeks for a DB" from a backend developer becomes the job get a database today, the noun database (size and environment), and the PostgreSQL API, one per environment. "I copy the last repo" from a new team lead becomes start a service right with a repo and CI, the noun application, and NodeJSApplication plus Python, Go and Spring Boot. "Where does the key go?" from a frontend developer becomes keep secrets out of git, the noun secret store, and the SecretStore API, one per app and cluster. "Is staging even up?" from a QA engineer becomes trust what green means, the noun health, and ComponentReady, a condition on every component. A loop runs from the API column back to the first: show it back to the people who said it. WHAT WE HEARDTHE JOB TO BE DONETHE NOUNTHE API"Three weeks for a DB"backend developerGet a database todayself-service, same dayDatabasesize · environmentPostgreSQLone per environment"I copy the last repo"new team leadStart a service rightwith a repo and CIApplicationlanguage · versionNodeJSApplicationand Python, Go, Spring"Where does the key go?"frontend developerKeep secrets out of gitnever in a values fileSecret storeapp · clusterSecretStoreone per app and cluster"Is staging even up?"QA engineerTrust what green meansbefore a releaseHealthready · degraded · whyComponentReadyon every componentSHOW IT BACK TO THE PEOPLE WHO SAID ITDevelopers don't ask for XRDs. They tell you what hurts. The API is our translation.LEGENDWhat a developer saidOur reading of itThe API in AirframeReview loop

Listen for verbs

People describe waiting, copying and guessing. Each of those is a job the platform could do for them, and the job is what you design around.

Find the noun

A good API is a noun a developer already uses: a database, an application, a secret store. If you have to explain the name, it isn't one yet.

Close the loop

Take the draft schema back to the person who asked. "Would this have saved you the three weeks?" is the cheapest review you'll ever run.

Hangar · Airframe · Service catalog