An API is a promise you cannot withdraw once someone depends on it. Design accordingly: the cost of\ngetting it wrong is paid continuously by everyone who integrates.
\nExpose concepts the consumer thinks in. An interface that mirrors internal table structure leaks\nimplementation, breaks whenever storage changes, and forces consumers to reconstruct meaning you\nalready had.
\nName things as the domain names them. Consistency in naming, casing, date formats and identifier\nstyle matters more than any individual choice being optimal — an interface that is uniformly\nimperfect is learnable, and one that is inconsistently excellent is not.
\nMost integrations spend most of their code on failure. Give it the same care as the success path:
\nAdding an optional field is safe. Removing a field, renaming one, tightening validation, changing a\ndefault, or adding a required parameter are all breaking, and the last three break consumers who are\ndoing nothing wrong.
\nVersion when you must break, and be explicit about how long the previous version lives. A\ndeprecation without a date is a deprecation nobody acts on.
\nPrefer expansion over versioning where possible: a new optional field costs a consumer nothing, a new\nversion costs them a migration.
\nAny collection that can grow needs pagination from the first release — retrofitting it is a breaking\nchange to every consumer. Prefer cursors over offsets for anything that changes while being read;\noffset pagination silently skips and duplicates records under concurrent writes.
\nState rate limits in the contract and communicate them in responses. An undocumented limit is\ndiscovered in the consumer's production incident.
\n