An API is a contract. It documents what a system will do, what it will accept, and what it will return. That contract, once published and consumed by other systems, becomes one of the hardest things in software engineering to change.

The implication is significant: API design decisions made at the beginning of a system's life constrain what is possible years later. A poorly designed API is not just an inconvenience — it is technical debt that compounds with every consumer that depends on it.

The Resource vs. Action Debate: A Quick Comparison

The Resource vs. Action Debate

REST APIs designed around resources — nouns rather than verbs — tend to be more intuitive and more stable over time. The reason is that resources reflect the domain model, which changes slowly. Actions reflect current business process, which changes frequently.

When you expose POST /invoices/123/approve, you have encoded a business process into your API. When the approval workflow changes — and it will — the API needs to change, which breaks every consumer.

Process of Engineering

1. 1Define the problem and identify core constraints clearly
2. 2Research existing solutions and map the technical landscape
3. 3Design the architecture with long-term scalability in mind
4. 4Validate early with stakeholders before full build-out

When you expose PATCH /invoices/123 with a status field, you have exposed the state of the resource. The workflow that drives state transitions is internal to your system. Consumers set state; they do not invoke processes.

Versioning as a First-Class Concern

API versioning is a decision that most teams defer until it is urgent, at which point the options are all painful. Building versioning into the API from the start — whether via URL versioning, header versioning, or field-level versioning — is a small investment with significant long-term returns.

The question is not whether your API will need to change. It will. The question is whether you have a path to make that change without breaking existing consumers.

Benefits of Engineering

The API is not a technical artifact. It is the product surface that other engineers will use to build their systems. Design it accordingly.