IT · 8 min
APIs that age well
An API is a promise to other software. Treat it like a contract, not a convenience.
Name the consumers. Internal app, partner, mobile client, batch job — each fails differently. An endpoint that is fine for one screen can melt a nightly import.
Stability beats cleverness. Keep URLs, field names and error shapes dull. If you must change, add a version or a new field. Removing a field that someone already stored is a break, even if you 'didn't mean it'.
Authentication belongs in the design, not as a header you remember later. Who is the caller. What can they read. What can they write. How do you revoke them. Write that before the first public URL.
Idempotency for anything that creates money, tickets or accounts. Timeouts and retries will double a payment if you let them. Clients will retry. Plan for it.
Document with examples of real requests and real errors. A list of endpoints without payloads is a menu without prices. Keep the document next to the code so it can rot in public view.
When Shefa builds APIs, scope includes consumers, auth, versioning and the first three error cases. That is the work. The framework is secondary.