Rule granularity is the degree to which a linting rule limits verification to one narrowly defined API aspect. Appropriate granularity keeps feedback useful; overly broad rules overwhelm users, enforce unnecessary patterns, or encourage bad APIs. section 18.4
The same principle applies to API data and operations: retain relevant data within scope, separate distinct capabilities, and combine information only when the combined purpose is clear. section 8.7 section 9.9.1
Use granularity to make API guidance easier to understand and apply:
- Create only rules justified by API design guidelines. section 18.4
- Split broad needs into small rule-sized checks, then combine them to cover larger topics. section 18.4
- Give each rule a concise name and description, and use shared OpenAPI components to simplify what it verifies. section 18.4
Account operations
A GET /accounts/{accountId} response that includes transactions forces consumers to filter, sort, and paginate unrelated data. A dedicated transaction-search operation has clearer granularity, while a dashboard operation may intentionally combine summarized accounts with recent transactions. Likewise, update customer address separately from account updates because the account and its holder are distinct concepts. section 9.9.1
Figure 8.8 How to design user-friendly, interoperable data
Use the design sequence to reconsider data relevance and granularity after selecting and organizing the data, then refine names and standards. section 8.3.3
