Understanding SPI vs API: Interface Placement and Design Principles

Background

The author, a senior architect, introduces the topic of interface design and the need to differentiate between SPI and API.

Three Possible Locations for an Interface

Place the interface in the caller's package.

Place the interface in the implementer's package.

Place the interface in an independent package.

Interface in the Caller’s Package

Using a repository interface placed in the domain layer (caller’s package) while the implementation resides in a separate package preserves the principle of programming to an interface. This arrangement avoids circular dependencies and keeps the domain services dependent only on the interface.

SPI Definition and Rules

SPI (Service Provider Interface) is a contract that allows different service implementations to be loaded at runtime. The rules for SPI are:

Conceptually depends more on the caller.

Organized in the caller’s package.

Implementation resides in an independent package.

Commonly used in plugin architectures.

The term service provider interface is highlighted in the original text.

Interface in the Implementer’s Package

When an interface such as IUnityContainer is defined and implemented within the same package, it behaves as an API rather than an SPI, because the contract is closer to the implementer.

API Definition and Rules

API (Application Programming Interface) defines a set of functions, protocols, and tools for building software applications. Its rules are:

Conceptually closer to the implementer.

Organized in the implementer’s package.

Implementation and interface are co‑located in the same package.

Interface in an Independent Package

Both SPI and API can be placed in a separate, independent package. Whether an interface is treated as SPI or API depends on the context and usage.

Key Considerations for Choosing Between SPI and API

Extensibility : SPI is preferable when functionality must be extended without code changes.

Interaction : API suits stable internal or inter‑system contracts.

Dynamic Loading : SPI supports runtime discovery and loading; API is usually resolved at compile time.

Security and Stability : API offers predictable stability, while SPI’s flexibility may introduce runtime risks.

Versioning and Compatibility : API changes require careful version control; SPI can handle compatibility via service version negotiation.

Conclusion

Architecture is about trade‑offs rather than a silver bullet; the choice between SPI and API should be guided by the specific requirements of extensibility, interaction, dynamism, and stability.