The Cost of a Promise

Short summary

A well-reasoned essay on API design as a long-term contract with consumers. Good APIs prioritize predictability, restraint, and consistency over cleverness and flexibility. Versioning is really about change management, not URL conventions, and every field or parameter added is a maintenance commitment that compounds over time.

• •APIs are promises that are hard to change without breaking trust
• •Restraint and consistency matter more than flexibility and perfection
• •Design for failure: clear errors, idempotent operations, meaningful status codes

Generated with AI, which can make mistakes.