While both API and SOA have similar business and technical goals, many API proponents continue to describe APIs as a significantly different approach with little connection to SOA. They often promote a deep and divisive schism between pragmatic REST APIs and SOA. The division inhibits cleanly integrating SOA services and RESTful APIs into a unified architecture.
Teams must bridge the divide between SOA and API perspectives and build a pragmatic plan reconciling API and SOA.
Teams ‘doing REST’ and ‘building APIs’ commonly focus on overcoming technical and business adoption barriers by pursuing incremental build-outs and demonstrating concrete, core-business use cases without introducing complex technology. SOA teams commonly focus on obtaining efficiencies at scale, achieving enterprise standardization, centralizing decisions, and satisfying complex non-functional requirements.
By combining API and SOA perspectives, teams can rapidly deliver business solutions while conforming to enterprise policy and scale requirements.
Pragmatic REST API focus
REST is an architectural style of system development imposing a series of constraints on service interactions. Formal REST constraints include client-server and stateless interactions, cached responses, uniform contract, layered system design, and code-on-demand. The constraints allow beneficial properties to emerge, namely simplicity, scalability, modifiability, reliability, visibility, performance, and portability. Systems satisfying REST constraints are RESTful. A RESTful design approach can foster many benefits:
- Make data and services maximally accessible
- Low barrier to entry
- Extend reach towards the largest possible audience
- Make API/service consumable by the largest number of user agents
- Make data and services evolvable
- Extend the system at runtime
- Alter resources without impacting clients
- Direct client behavior dynamically
- Make systems scalable, reliable, and high performing
- Simple
- Cacheable
- Atomic
While RESTful design benefits support SOA goals, the strategic focus of Pragmatic REST differs from many SOA initiatives. Pragmatic REST API design teams focus on bottoms-up adoption scenarios, approachable protocols/formats (e.g. HTTP, JSON, DNS), permissive interface definitions, and simpler interaction models (i.e. retry over guaranteed delivery).
Pragmatic SOA focus
Pragmatic SOA focuses on service-oriented patterns that increase software asset value. The fundamental service-oriented patterns are:
- Share and reuse assets
- Consolidate redundant functionality into fewer moving parts
- Conform projects to common standards and best practices
Applying these three patterns will reduce complexity within an IT environment and lead to greater agility, i.e., the ability to build applications faster and modify them quickly to address changing requirements. The service-oriented patterns force development teams to evaluate how software asset capabilities meet the needs of business stakeholders.
Pragmatic SOA Best Practices
Pragmatic SOA teams don’t force common (yet complicated) standards. Pragmatic SOA teams offer useful business capabilities, reduce adoption friction, and deliver exceptional service values.
Pragmatic SOA teams don’t preach difficult best practices. Pragmatic SOA teams simplify best practice adoption by mentoring teams and delivering automated governance that makes the right thing to do the easy team to do.
Pragmatic SOA teams are mindful of skill gaps and adoption hurdles. Pragmatic teams offer accelerator packs (i.e. infrastructure, tooling, frameworks, and API/service building blocks) that reduce training, increase self-service adoption, and accelerate project delivery.
Pragmatic SOA teams balance enterprise governance with project autonomy. Instead of erecting development and registration barriers, successful teams foster service development, service sharing, and service adoption by introducing mechanisms to promote services, mediate interactions, harden service levels, and facilitate self-service adoption. You may recognize these mechanisms as being the core of API management.
Pragmatic Reconciliation
REST is different from—although not incompatible with—SOA. Services can be RESTful, and RESTful resources can be services. Like SOA, REST is an architectural discipline defined by a set of design principles, and REST also imposes a set of architectural constraints. REST uses a resource-centric model, which is the inverse of an object-centric model (i.e., behaviors are encapsulated by resources). In REST, every “thing” of interest is a resource. When modeling a RESTful service (aka APIs), the service's capabilities are encapsulated and exposed as a set of resources.
Because SOA presents an architectural goal state that is often at odds with the existing legacy IT portfolio, SOA is a long-term architectural journey, and not a short-term implementation initiative. Because APIs interconnect business capabilities inside and outside the organization, APIs can provide a platform for business stakeholders sponsoring enterprise IT renewal and pragmatic business execution.
When to Create Services or APIs
When creating a unified architecture strategy embracing SOA and REST, a logical next question is when to create a service or an API. From a messaging perspective, services and APIs have similar attributes. They are both network accessible endpoints delivering data or triggering a transaction. From an architecture perspective, both services and APIs provide an opportunity to create loosely coupled solutions exhibiting separation of concerns. Many architects and developers desire to extend their Service Oriented Architecture (SOA) with APIs, but are not clear on when to create a service or create an API.
When to create a service?
A service is a business function or data published as a network accessible endpoint. Teams create services when sharing business capability or business data across network domain or run-time application boundaries.
A service should implement a reasonably autonomous business task and not be designed as a fine-grained component with interdependencies on other components. Developers and business analysts are more likely to understand the service’s purpose when the service exposes a discrete task within a business process. Designing services for business task granularity reduces service interaction complexity and simplifies application maintenance. Examples of business tasks that are compatible with a service-oriented approach include “submit order,” “retrieve customer record,” and “pay bill.”
Separating Interface From Implementation
Services encapsulate distinct implementations, and service endpoints often have a one-to-one association between service and backend business logic. A service should expose a business capability or data through multiple interface styles (e.g. resource oriented, publish/subscribe, method invocation). To maximize availability and reach, a service implementation should publish interfaces accessible via multiple message protocols (e.g. HTTP, JMS, MQ) and message formats (e.g. JSON, XML, CSV).
RESTful APIs are an interface style. A style well suited when mobile applications, thin client JavaScript applications, and bash scripts access functionality across network and ownership domains.
Ideally, the interface style is just a solution detail, and important management characteristics (i.e. security, service level enforcement, usage tracking) are available across all interface style channels (e.g. resource oriented, publish/subscribe, method invocation). Figure 1 illustrates implementing a facade pattern to connect a single service implementation with diverse consumers:
Figure 1. API Façade Pattern
Separating external contract and external protocols from internal representation positively impacts the ability to evolve the service implementation over time. When a clean separation of interface from implementation exists, a developer can modify the implementation without impacting calling applications that use the service.
However, decoupling consumer and provider from a shared application platform, and decoupling interface from implementation raises additional concerns. For example, difficulties arise when attempting to seamlessly flowing operational semantics (i.e. identity, service levels, authorization) across dissimilar platforms and a distributed environment. Teams rely on middleware infrastructure to bridge the semantics across all participating parties and components.
Because separating interface from implementation introduces complexity and extra development effort, many teams tightly bind interface to implementation. By following architectural best practices and introducing API facades or proxy endpoints (with development automation), teams increase solution maintainability and adaptability.
When to create RESTful APIs?
RESTful APIs are an interface style complementary to service implementations. Create a RESTful API when sharing a service outside a domain of control (i.e. business unit, organization), targeting the widest possible reach and consumption, offering the service across native web infrastructure, or interested in maximizing asymmetric evolution between service clients, interface, and implementation.
When development teams publish API facades in front of existing services, they explicitly separate service interface from service implementation. API endpoints are lightweight proxies enforcing security, monitoring usage, and shaping traffic. The proxy enables a clear separation of concern between consumer interface contract and back-end service implementation.
While application servers, enterprise service bus nodes, or data service hosts could publish API endpoints, API gateways are the preferred managed API delivery mechanism. A managed API is:
- Actively advertised and subscribe-able
- Available with an associated, published service-level agreement (SLA)
- Secured, authenticated, authorized and protected
- Monitored and monetized with analytics
Service Interface or RESTful API Interface
RESTful APIs are different from—although not incompatible with—services. Services can be RESTful, and RESTful resources can be services. Like SOA, REST is an architectural discipline defined by a set of design principles, and REST also imposes a set of architectural constraints.
RESTful API interfaces are a constrained subset of service interfaces. RESTful APIs expose a resource-oriented interface, and ideally conform to HATEOS (Hypertext as The Engine Of State). RESTful APIs publish a resource-centric model, which is the inverse of an object-centric model (i.e., behaviors are encapsulated by resources). In REST, every “thing” of interest is a resource. When modeling a RESTful service (aka APIs), the service's capabilities are encapsulated and exposed as a set of resources.
To create a RESTful API:
- Give every thing an ‘ID’
- Link things to each other
- Use standard HTTP methods
- Allow for multiple message format representations
- Reduce shared state
Emerging API design tools will help you convert a service implementation into a RESTful API.
About the Author
Chris Haddad leads platform evangelism at WSO2. He lives in Space Coast Florida, where he watches rocket launches, rides the ocean surf, and writes about architecture best practices Chris converges pragmatic hands-on practitioner experiences with IT business goals to communicate strategies and tactics when adopting Cloud, DevOps, and API-centric architecture.
