An API is a contract, and contracts are expensive to change once someone's depending on them. The difference between an API that's pleasant to maintain years later and one that accumulates awkward workarounds usually comes down to a handful of decisions made early, when they're cheap.
Design around resources and intent, not implementation details
An API that mirrors your database schema exactly tends to break the moment your database schema needs to change for reasons that have nothing to do with the API contract. Designing endpoints around what a consumer is actually trying to accomplish, rather than around your internal data model, gives you room to refactor the implementation without breaking the contract.
Version deliberately, from the start
Deciding on a versioning strategy before you need one — whether that's a version in the URL, a header, or another mechanism — is far easier than retrofitting versioning onto an API that's already been consumed by clients who assumed it would never change. Even if you don't expect breaking changes soon, having the mechanism in place means you're not making a rushed decision under pressure when you eventually need it.
Consistent error handling is not optional
Every error response should follow the same shape and convey enough information for the consumer to know what happened and, ideally, what to do about it. Inconsistent error formats — a string here, a structured object there, a bare HTTP status code with no body somewhere else — push complexity onto every consumer of your API, forcing them to handle each case differently instead of writing one error-handling path.
Document behavior, not just shape
A schema tells a consumer what fields exist. It doesn't tell them what happens when a required field is missing, what the rate limits are, or what idempotency guarantees exist for a given endpoint. The undocumented behavioral edges are exactly where integration bugs happen, and they're also the cheapest thing to document — usually a paragraph, not a diagram.
Idempotency matters more than teams initially assume
Network calls fail and get retried, sometimes by a client, sometimes by infrastructure in between. Endpoints that perform a mutation — creating a record, charging a payment — should be designed so a retried request doesn't duplicate the effect, typically via an idempotency key the client supplies. Skipping this is fine until the first time a retried request creates a duplicate charge, at which point it becomes an urgent problem instead of a design decision made calmly in advance.
Build for the consumer who'll change this in two years
The most durable API design habit is imagining the person who'll need to extend this API long after the original context has faded — quite often, that person is you. Clear naming, consistent patterns, and documented edge-case behavior are a gift to that future maintainer, and the cost of providing them upfront is genuinely small compared to the cost of reconstructing that context later from scratch.