Testing an API is not the same as testing a library or a UI. An API is a contract — a public interface that other systems depend on — and the testing strategy must reflect that. Unit tests tell you whether individual functions work. Integration tests tell you whether the system behaves correctly end to end. Contract tests tell you whether the API still honors its published interface. Load tests tell you when it breaks. All four serve distinct purposes and none is a substitute for the others.

APIs are contracts. When you publish an API and someone builds an integration against it, they are betting their system on your endpoint continuing to behave as documented. Versioning is how you preserve that contract while still being able to evolve the underlying system. Done well, it gives you forward momentum without leaving integrators behind. Done poorly, it creates a maintenance burden that accumulates until one side gives up.

What Counts as a Breaking Change

The most important skill in API versioning is recognizing what requires a version increment. A breaking change is anything that causes a previously valid, working integration to fail or behave differently without modification. This is a broader category than most developers initially assume.

HTTP is a synchronous protocol. A client sends a request and waits for a response. This works well for operations that complete in milliseconds — a database read, a record update, a validation check. It breaks down for operations that take seconds, minutes, or longer: video transcoding, report generation, bulk data exports, machine learning inference on large inputs, email campaigns to millions of recipients.

Holding an HTTP connection open for a minute or more is technically possible and practically wrong. Clients time out. Load balancers have maximum request durations. Users cannot tell the difference between a server still working and a server that silently failed. Long synchronous operations produce brittle integrations and poor user experiences.

The standard REST pattern is one resource per request. Create one user, update one order, fetch one product. This works until an integrator needs to create ten thousand users, update five hundred orders, or sync an entire product catalog. Making ten thousand individual API calls is slow, expensive in terms of rate limit quota, and brittle — a network failure on request 7,432 leaves the integrator with a partially completed operation and no clean recovery path.

HTTP was designed from the beginning to support multiple representations of the same resource. A user profile can be represented as JSON for a machine consumer or as HTML for a browser. A dataset can be returned as JSON or as CSV depending on what the client intends to do with it. An image can be served as JPEG or WebP based on what the browser supports. Content negotiation is the mechanism through which clients and servers agree on which representation to use — and understanding it is essential for building APIs that serve diverse consumers cleanly.

CORS is the source of more developer frustration than almost any other browser security mechanism — not because it is poorly designed, but because its error messages are opaque, its rules are non-obvious, and it only manifests in a specific context that server-side developers often do not encounter during development. Understanding what CORS actually is and why it exists transforms it from an arbitrary obstacle into a predictable system with clear rules.

Developer experience is not a soft concern. It determines how quickly developers integrate your API, how many support tickets they file, how many abandon the integration and use a competitor, and how they describe your product to other developers. An API with good developer experience turns integrators into advocates. An API with poor developer experience turns them into complaints.

Good DX is not a single feature or a checklist item added at the end of the design process. It emerges from a series of small decisions made throughout design and implementation. Every naming convention, every error message, every documentation page, and every SDK is a DX decision.

APIs designed for desktop web clients on reliable broadband do not perform well on mobile without deliberate adaptation. Mobile clients operate under constraints that server-side developers often underestimate: variable and often poor network conditions, limited battery budgets where every radio transmission costs energy, smaller screens that need different data shapes than desktop, and the expectation of usable offline states that desktop web apps rarely require. Building an API that serves mobile clients well requires understanding these constraints and making design decisions that account for them.

File handling is where many otherwise well-designed APIs cut corners. The result is integrations that work fine for small files and break under production conditions: uploads timing out on slow connections, downloads failing midway through large transfers, clients with no way to resume an interrupted operation. File upload and download have well-established patterns that handle these conditions correctly. Most of them require explicit design choices rather than the defaults.

Simple Upload: When It Is Sufficient

For files under a few megabytes that users upload infrequently, a direct multipart form upload to your API is the simplest approach. The client sends a multipart/form-data POST request with the file as one part and any metadata as additional parts or as a separate JSON field:

GraphQL shifts the design work from endpoint definition to schema design. The schema is the API — every type, field, query, and mutation is declared in the schema, and the schema governs everything the API can do. Designing a GraphQL schema well requires understanding how types compose, how to express mutations that reflect real domain operations, and where GraphQL’s conventions differ meaningfully from REST patterns that GraphQL developers often import by habit.