Signs it is time to revisit API design
This is cheap to get right at the start and expensive to retrofit. A few signals that API design is due some attention.
The question is rarely whether something can be built, but what it costs to keep running afterwards. Assume whoever inherits this will have half your context and none of your patience.
The signals
- Nobody can say when it was last reviewed
- The answer depends on who you ask
- Consistent naming saves every future integrator hours
- Version the API before anyone else depends on it
How we handle it
Errors should be as well designed as successes. This is the sort of thing that compounds, quietly, in both directions. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.
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
- Errors should be as well designed as successes — and you know whether that is true here
- There is a way to tell whether the last change to this helped
If you are not sure where your systems currently stand on this, it takes us about an hour to find out.