The short answer
An API is a contract you cannot easily change once someone depends on it. The decisions that hurt later are almost never about speed; they are about how you version, how you report errors, and how you paginate. Get those three right at the start and the rest is refactorable.
The three that bite
Versioning
- Decide before launch, not when the first breaking change is already needed.
- Every response shape is a promise; additive change is safe, removal is not.
Errors
- A consistent error envelope with a machine-readable code beats a human-readable string.
- Clients will parse whatever you give them — give them something stable.
Pagination
- Offset pagination breaks under concurrent writes; cursors do not.
- Retrofitting this after clients depend on page numbers is a migration, not a fix.
The things that matter less than teams argue about
- REST versus GraphQL, in most products. Both work; consistency matters more than the choice.
- Perfect resource modelling. Ship the endpoints the client needs.
- Micro-optimising response size before you have a measured problem.