A trade-off balances one benefit against a corresponding disadvantage or cost. API design rarely offers a perfect solution: each option affects users, consistency, complexity, performance, compatibility, or operational safety. section 2.3.3 section 24.4
Evaluate a trade-off by making the competing consequences explicit:
- Compare alternative designs instead of treating the first obvious solution as sufficient; even query parameters and relationship models can have subtle implications. section 2.3.3
- Prefer consistency when several approaches are viable, while documenting why one option was selected. section 2.3.3
- Separate immediate simplicity from long-term costs, such as distributed monitoring, additional API calls, memory use, or compatibility limits. section 10.4 section 13.4
- Choose deliberately for the scenario rather than applying a universal rule; user needs, regulations, data sensitivity, and failure consequences change the balance. section 25.4 section 26.4
Filtering versus client-side retrieval
A list endpoint can provide filtering, accepting greater server resource use in exchange for smaller responses and less wasted client and API work. An unstructured filter string may also ease future format changes, but requires clear documentation and continued support for new formats. section 22.4 section 22.4
Good API design does not eliminate trade-offs. It identifies the relevant spectrum, chooses where the API should sit, communicates the policy, and applies it consistently. Avoid making compatibility, deletion, retry, or feature decisions ad hoc. section 24.4 section 24.4.2
