In today's fast-paced digital landscape, organizations are constantly seeking ways to deliver value more rapidly and efficiently. I have coined the concept of "Vertical Velocity"— the ability of cross-functional teams to deliver complete end-to-end business value continuously without waiting on or blocking other teams. But achieving this velocity requires more than just reorganizing teams; it demands a fundamental shift in how we think about system boundaries and interfaces.
The Three Levels of Alignment
True Vertical Velocity doesn't happen by accident. It requires seamless alignment across three critical levels:
Organizational: Stream-aligned feature pods with end-to-end domain ownership that can operate independently and make autonomous decisions.
Architectural: Well-defined bounded contexts designed with clear business domain boundaries that reflect how your business actually operates.
Technical: Intentionally designed API interfaces—whether governed by explicit schemas or self-describing hypermedia controls—that establish clear, resilient boundaries between services.
When these three levels are in harmony, teams can move independently, deploy autonomously, and deliver value continuously. But when they're misaligned, even the most empowered agile feature pods will stall against rigid, brittle software boundaries.
Understanding Conway's Law in Practice
Any serious discussion about aligning team structure with technical boundaries inevitably leads to Conway's Law: Organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations.
If you want cross-functional feature teams to thrive, you must design boundaries that allow them to operate independently. In Domain-Driven Design (DDD), these are called Bounded Contexts. By drawing hard boundaries around specific business domains, you allow teams to own a domain entirely.
But how do those bounded contexts communicate? Through APIs.
Rethinking Our Relationship with APIs
Historically, we treated APIs simply as pipes connecting one server to another—passive, data-centric, and brittle. Every schema change breaks consumers, and business logic leaks into the client layer. These "Pipe APIs" were afterthoughts, accidental byproducts of implementation rather than deliberate design decisions.
In a modern ecosystem, however, an API is the primary user interface of your bounded context. We need to build "Product APIs" that expose business capabilities, not database tables. A Product API encapsulates business rules, ensures data validity before persistence, and provides semantic, meaningful operations to its consumers.
When you treat your API as an afterthought—as a simple data pipe—you invite cognitive load, integration nightmares, and API drift: the gradual divergence between your documented API contracts and your actual implementation, often caused by developers forgetting to update wiki pages or README files when they make changes.
The Principle of API-First Design
The principle is straightforward: treat your API—its semantics, behavior, and constraints—as a first-class concern in your architecture, not an accidental byproduct of your implementation. This is API-First Design.
But "API-First" doesn't mean "OpenAPI-First" or "Contract-First." It means something more fundamental: that the interface between services deserves deliberate design, regardless of the paradigm you choose.
Choosing the Right Approach
There are multiple valid approaches to API design, each with its own strengths:
Contract-First: You publish a machine-readable specification that describes every endpoint, request, and response. Clients consume this contract and hardcode their interactions accordingly. This offers exceptional tooling, type safety, and validation—but at the cost of tighter coupling. Any change to the contract requires coordination.
Hypermedia-Driven: You design your API to guide clients through hypermedia links embedded in responses. Clients discover available actions dynamically, navigating from resource to resource without hardcoding URL structures. This offers loose coupling and evolutionary flexibility—but requires more sophisticated clients and a deeper understanding of REST principles.
Both approaches are "API-First." Both require deliberate design, clear semantics, and a focus on the consumer experience. The difference lies in how you communicate your API's capabilities.
The Right Tool for the Right Context
Different contexts call for different approaches:
- Where data integrity is paramount, Contract-First with OpenAPI shines
- Where discoverability is key, Hypermedia-Driven REST with HATEOAS excels
- Where temporal decoupling matters, Event-Driven architectures make sense
- For high-performance internal communication, protocols like gRPC deliver
What unifies these approaches is a shared commitment to designing APIs intentionally, with the consumer in mind, and treating the interface as a boundary that enables parallel work and independent evolution.
Unlocking the Benefits
When your API is designed intentionally—regardless of the paradigm—you unlock transformative benefits:
- UI developers can build and test against clear expectations before the backend exists
- Backend developers have clear guidance on what to implement
- Integration teams can validate compatibility automatically
- Evolution becomes manageable through versioning, deprecation policies, or the inherent flexibility of hypermedia
The Lost Promise of REST
Most of what we call REST today is actually RPC-over-HTTP—a collection of remote procedure calls that happen to use HTTP as a transport. True REST, with hypermedia as the engine of application state, offers powerful decoupling but has been largely ignored in practice. There are good reasons for this: hypermedia-driven REST requires sophisticated clients, adds complexity, and demands a deeper understanding of architectural principles. For many use cases—especially external APIs where clients need predictability—a contract-first approach is simply more practical.
The lost promise of REST isn't a failure of REST itself. It's a failure to match the right approach to the right context. Sometimes you need a map (explicit contract). Sometimes you need signposts (hypermedia). And sometimes you need something else entirely.
The Path Forward
Achieving true Vertical Velocity requires a commitment to intentional API design. It means designing boundaries that allow teams to operate independently, choosing the right interface patterns for each context, and treating your API as the critical business asset it truly is.
The principle is constant: design your API first. The specific tool depends on your context. But the commitment to deliberate, consumer-focused design is what enables the organizational velocity that modern businesses demand.
No comments:
Post a Comment