An API is an interface between programs. Design it from the client's point of view before implementation details take over. A stable resource model, predictable methods, and consistent responses save every caller from learning one-off rules.
A practical design sequence
- Name the resources and their relationships.
- Choose URLs that identify collections and items.
- Map reads, creates, updates, deletes, and custom actions to HTTP methods.
- Define request and response bodies, status codes, errors, and retry behavior.
- Add pagination, sorting, and filtering to collection endpoints.
- Write an OpenAPI description and try the interface from a client before coding the service.
The detailed pages follow that sequence. Start with REST, then read URL design and methods and idempotency.
API design map
| Page | Focus |
|---|---|
| REST | Constraints, representations, and maturity |
| URL design | Resource paths, hierarchy, versioning, and parameters |
| Methods and idempotency | Method intent, retries, and custom actions |
| CRUD endpoints | Route map, response bodies, and status codes |
| List APIs | Pagination, sorting, filtering, and defaults |
| Consistency | Naming, documentation, and interface rules |
Use communication protocols for the network context and availability and consistency when an API crosses replicas or regions.