16 Facilitating API design decision-making
- Making design decisions confidently and consistently
- Researching solutions to API design questions
- Creating and evolving API design guidelines
Should we use an IBAN or an account number to identify a bank account? “Owner” or “user”? /accounts or /account? 403 or 404? Boolean or string? How do we handle pagination? Designing an API involves countless decisions to fulfill user needs; be user-friendly, secure, efficient, and extensible; integrate contextual constraints; and not break consumers. Any decision can have significant consequences or introduce inconsistency. We may struggle to choose one option among many, have no clue how to solve a problem, or endlessly repeat the same discussions (sometimes with different conclusions). All this can make API design decision-making inefficient, inconsistent, and daunting.
16.1 Making design decisions confidently and consistently
16.1.1 Ensuring that it’s the right time to make a decision
16.1.2 Evaluating the scope of the decision
16.1.3 Deciding based on trusted past decisions
16.1.4 Deciding based on trusted external sources
16.1.5 Backing decisions with reasoning and sourced information
16.1.6 Explaining out loud
16.2 Researching solutions to API design questions
16.2.1 Where to research solutions to design questions
16.2.2 Searching and considering
16.2.3 Using an architectural decision record format
16.3 What are API design guidelines?
16.3.1 How design guidelines can help us
16.3.2 How API design guidelines relate to API governance
16.3.3 When do we need design guidelines?
16.4 What to put in user-friendly API design guidelines
16.4.1 Listing principles and rules
16.4.2 Providing actionable recipes
16.4.3 Providing ready-to-use artifacts and tools
16.4.4 Helping with the API design process
16.4.5 Adding implementation or architecture considerations
16.5 How to build API design guidelines