Consistency applies the same names, types, formats, structures, identifiers, and behaviors across related API data and interfaces. It helps developers predict what they will find, reuse their experience, and code with fewer surprises. Apply it within an API first, then align with organizational, domain, industry, or global standards when they fit consumer needs. section 8.9 section 8.9.1
Apply consistency across the API surface:
- Model resources first, then derive operation inputs and outputs from those models so shared data remains aligned while server-generated fields stay out of create requests. section 5.1.3
- Reuse names, formats, and units for equivalent data; represent location consistently rather than mixing a familiar location field with an unusual array format. section 8.2.4
- Make operation paths and behaviors predictable: use GET /shops, POST /shops, and GET /shops/{shopId} rather than switching between plural and singular paths. section 9.1.3
- Standardize identifiers and representations, such as using an IBAN for accountId, ISO 4217 currency codes, and one recognizable id property across resources. section 9.10.1
- Use similar flows for similar use cases, including predictable GET, PUT, or PATCH sequences and reusable file-upload patterns. section 10.1.6
Avoiding identifier confusion
Suppose GET /customers returns a customer ID, while account creation requires a customer reference returned by GET /customers/{customerId}. Both identify a customer, but their different names and contexts can cause troubleshooting. Hide such internal complexity or confirm that the identifiers represent genuinely distinct concepts. section 9.10.1
Consistency is not blind reuse. Check existing models and standards, including domain standards such as ISO 20022, but reject material that is too complex or fails consumer requirements. When no standard fits, reuse proven patterns for types, formats, organization, names, and behaviors. section 8.9.1
Figure 5.7 We use theoretical resource models to design inputs and outputs. We ensure that data meets consumer needs without exposing inner workings; we especially check input sources for gaps in capabilities.
Trace how theoretical resource models become operation inputs and outputs while checking consumer needs and avoiding exposure of implementation details. section 5.1.3
