When to Choose SPI vs API? A Deep Dive into Interface Placement

Background

The author first encountered SPI while reading "The Art of Software Framework Design" and later observed similar patterns in JDBC and SpringBoot, prompting a reflection on why SPI and API should be distinguished.

Interface‑Oriented Programming

When introducing an interface between a caller and an implementer, three package placement options exist:

Place the interface in the caller’s package.

Place the interface in the implementer’s package.

Place the interface in an independent package.

The article analyzes each possibility with concrete examples.

1. Interface in the Caller’s Package (SPI)

Using a repository interface placed in the domain layer (caller’s package) while the implementation resides in a separate package follows Domain‑Driven Design practices. The domain service depends on the repository interface, and the repository interface depends on the aggregate root. Moving the interface to the implementation package would break the interface‑oriented design, and placing it in an independent layer would cause compilation errors due to circular dependencies.

Such an interface is classified as an SPI (Service Provider Interface) with the following rules:

Conceptually depends more on the caller.

Organized in the caller’s package.

Implementation lives in an independent package.

Typical example: plug‑in architecture.

2. Interface in the Implementer’s Package (API)

Consider the IUnityContainer interface from Unity. The interface is defined alongside its implementation, making it an API (Application Programming Interface). API rules are:

Conceptually closer to the implementer.

Organized in the implementer’s package.

Implementation and interface share the same package.

3. Interface in an Independent Package

If an interface serves as an API in one context and an SPI in another, it can be placed in an independent package to accommodate both roles.

Key Considerations

Regardless of whether an interface is SPI or API, placing it in an independent package is permissible, but the decision should be based on the specific architectural needs.

SPI Definition and Usage

Definition: SPI is a service‑provider interface that allows different service implementations to be loaded at runtime.

Modular design: separates core functionality from concrete implementations.

Plug‑in architecture: supports multiple interchangeable service implementations.

Service discovery: dynamically loads services based on configuration or a registry.

Micro‑service architecture: enables dynamic interaction between services.

Advantages:

Increases flexibility and extensibility by allowing runtime selection of implementations.

Supports hot‑swapping of services without restarting the system.

API Definition and Usage

Definition: API is a set of predefined functions, protocols, and tools that define contracts for interaction between software components.

Client‑server communication: designs protocols for interaction.

Libraries and frameworks: provides public interfaces for developers.

Third‑party integration: connects with external systems or services.

Internal component communication: enables interaction between modules in large systems.

Advantages:

Provides clear documentation and specifications, making it easy to understand and use.

Helps maintain system stability through versioning and compatibility rules.

Promotes code reuse and modularity.

How to Choose Between SPI and API

Consider the following factors:

Extensibility: SPI is better when you need to add functionality without changing existing code.

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

Dynamics: SPI allows runtime discovery and loading; API is usually fixed at compile time.

Security and Stability: API’s predictability often makes it preferable for stable systems, while SPI’s flexibility can introduce runtime risks.

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

Architecture is about trade‑offs, not a silver bullet.