15.5 · Designing a Swift API: naming, ownership, documentation and evolution

An API is a promise to every caller you will never meet. The cost of a bad name or a leaky type is paid every time it is used, and every time you try to change it.

Mental model. Design for the call site: it should read like a sentence, make misuse hard and be cheap to evolve without breaking users.

Designing the surface

Naming, labels, defaults, ownership and documentation.

1. What makes a good Swift API: naming, argument labels, defaults, ownership, thread documentation and misuse resistance? 15.5.1 · L5
   Swift’s API Design Guidelines start from clarity at the point of use: judge a name by how the call reads, not the declaration. Naming: omit needless words and…

Changing it later

Deprecation, renames and evolution.

1. How do you evolve a public API without breaking callers: deprecation, renames, versioning and source versus binary compatibility? 15.5.2 · L5
   A published API is used by code you cannot see, so change is a process, not an edit. First know what “breaking” means. Source compatibility: callers recompile…

More in Architecture & API design

• 15.1 · MVC, MVVM, MVP, VIPER, RIBs, TCA and Clean, and unidirectional data flow
• 15.2 · Coordinators, routers and dependency injection
• 15.3 · Feature modules and boundaries, and strangling a legacy codebase
• 15.4 · throws, Result, typed throws and mapping errors at boundaries
• 15.6 · SOLID without dogma, and building a platform for many apps
• 15.7 · Effects and cancellation, modelling state, composing reducers
• 15.8 · Closure-based clients, dependency lifetimes, generic repositories and building the graph lazily
• 15.9 · Binary breaks from innocent changes, and what an import exposes
• 15.10 · Types that prevent misuse, error types for libraries, one-shot values and when to trap