What makes a good REST API?
Understand the concept
A REST-oriented API exposes resources through consistent HTTP operations and representations. A useful API contract explains identifiers, input rules, outcomes, errors and pagination so clients do not need to guess. The goal is predictable behavior and evolvable interfaces, not forcing every business operation into a simplistic CRUD shape.
Important ideas
-
Use clear resources, consistent methods and meaningful status codes.
-
Validate input; support bounded pagination, filtering and stable sorting.
-
Return a consistent error code/message/request ID, without internal stack traces.
-
Use explicit action endpoints when they honestly represent a domain transition, such as submitting an order for approval.
Can you explain it without the notes?
What makes a good REST API?
Use your own words. Explain an example and one limitation before checking the explanation.
Check your explanation
A REST-oriented API exposes resources through consistent HTTP operations and representations. A useful API contract explains identifiers, input rules, outcomes, errors and pagination so clients do not need to guess. The goal is predictable behavior and evolvable interfaces, not forcing every business operation into a simplistic CRUD shape.
Turn this concept into a clear answer.
- Walk through a successful request, a validation error and a forbidden request using the same clear contract.
Adapted from 07_SYSTEM_DESIGN_ARCHITECTURE.md · “What makes a good REST API?”. Examples are study fragments; framework behavior can depend on your version.