Getting started with API design
The version of this that works is simpler than the version most people imagine. A short on-ramp to API design for teams who have not touched it before.
The question is rarely whether something can be built, but what it costs to keep running afterwards. Budget a little time for it every quarter and it never becomes a project of its own.
Why it matters
Consistent naming saves every future integrator hours. The cost of getting this wrong is rarely visible on the day it happens. The failure mode is not doing it wrong, it is doing it once and assuming it stays done.
Your first week
- Find out what is already in place
- Version the API before anyone else depends on it
- Change one thing and measure it
Errors should be as well designed as successes. There is a version of this that is over-engineered, and it is worth avoiding. It is worth deciding this deliberately rather than inheriting whatever the last person set up.
What this looks like day to day
Most development decisions are really maintenance decisions wearing a different hat. Three things worth confirming about API design before you move on:
- Someone can say what the current setup is without going to look
- Consistent naming saves every future integrator hours — and you know whether that is true here
- There is a way to tell whether the last change to this helped
None of this needs a rewrite. Most of it is a morning's work once someone decides to do it.