Extensibility is an API’s capacity to accommodate future capabilities or changes without disruptive redesign. It matters because consumed APIs must evolve while preserving usability, interoperability, security, and consumer trust. section 1.7.3 section 15.0
Design extensibility from the first version, then assess every proposed modification, its backward-compatibility effects, migration cost, and value. Versioning is a policy and architecture decision, not merely a number. section 15.1.2 section 15.1.3
Choosing extensible representations
Returning an array directly from GET /accounts leaves no place for future pagination metadata; returning an object from the beginning preserves room for additional fields. Likewise, arrays of objects can accommodate new element data more safely than arrays of atomic values. For recurring transfers, ISO 8601 durations such as P1M and P3M can grow to include P1W more naturally than fixed values such as MONTHLY and QUARTERLY. section 15.6.3
Use these design choices to reduce disruptive future changes:
- Use objects at request and response body level instead of top-level arrays or atomic values. section 15.6.3
- Prefer arrays of objects when each element may later need additional data. section 15.6.3
- Group related values in arrays when consumers can process added elements without interpreting every possible value. section 15.6.3
- Use enumerations carefully instead of restrictive Booleans, and consider operations instead of enumerations when capabilities may expand. section 15.6.3
- Document modifications with an updated version, changelog, and deprecated elements in OpenAPI. section 15.8
Figure 15.2 Handling design modification starts when we create an API. Modifying an API is “design as usual” with the addition of taking care of breaking changes and modification logs.
Use the modification workflow to connect initial extensible design with change assessment, versioning, and consumer communication. section 15.1.3
