Interfaces between systems.
WHAT AN API DOES
Exposes functionality for other software to use.
WHAT TO DECIDE
What resources exist What operations each supports What format is used How errors are reported
WHAT MOST USE
Structured data over HTTP.
WHAT TO MAKE CONSISTENT
The shape of every response, including errors.
WHY
Clients depend on it, and inconsistency produces defensive code everywhere.
WHAT TO RETURN
Appropriate status codes, matching what actually happened.
WHY
Returning success for a failure breaks everything downstream.
WHAT TO INCLUDE IN AN ERROR RESPONSE
What went wrong, specifically, in a consistent structure.
WHAT NOT TO INCLUDE
Internal errors, stack traces or system detail.
WHAT TO IMPLEMENT
Authentication Rate limiting Validation on every input Pagination on collections
WHAT TO DOCUMENT
Every endpoint: what it does, expects, returns, and can fail with.
WHAT TO VERSION
The API, before others depend on it.
WHY
Changing it afterwards breaks them.
