Understanding APIs: Contracts Between Applications
An API is a published contract between applications that specifies the exact rules for requesting and receiving services.
One Application, Many Services
An application does not always perform every task inside one self-contained program. It can request functionality from other applications that specialize in particular services. An API makes that cooperation possible by publishing the rules for requesting and receiving a service.
An Application Program Interface, or API, is a published contract between applications. The contract specifies the exact rules that one application must follow when requesting a service and the rules that describe what the responding application will return. The requesting application does not need to understand the service's internal implementation. It needs to follow the published contract.
Reading the Contract
- The application identifies the service functionality it needs.
- It creates a request that follows the service's published rules.
- The request includes what is being requested, parameters that customize the request, and authentication credentials if they are required.
- The service validates the request against its API contract.
- The service processes the request and sends a response.
- The application parses the response and uses the returned data to continue its work.
The contract governs both directions of the interaction. It describes what the requesting application must provide and what it can expect in return. A response typically contains the requested data in a standardized format such as JSON or XML, along with a status code indicating whether the request succeeded or failed.
Tracing a Travel Booking
Composing a Travel Booking Application
How can a travel booking application provide flight search, hotel availability, payment processing, and user account functionality without implementing every capability itself?
Identify specialized services: The application uses one service for flight data, another for hotel inventory, a third for payment processing, and another for user accounts.
Follow each service contract: Each service publishes the rules for making requests and the format in which it returns responses.
Coordinate the requests: The travel application acts as the orchestrator. It knows which services to call, in what order, and how to combine their responses.
Build one user experience: Although the work is performed by multiple independent services, the application combines the returned information into a cohesive travel-booking experience.
Separate services cooperate through their API contracts, while the travel application coordinates their work and presents one completed result.
The important idea is not merely that several services exist. The services can cooperate because each one publishes a contract. The travel application can coordinate them without knowing the internal implementation of flight search, hotel inventory, or payment processing.
SOA and Monolithic Design
| Design | Organization | How functionality is accessed | Important implication |
|---|---|---|---|
| Monolithic application | A single self-contained monolith | Functionality is contained within that application | The application is not composed of independent services connected across a network |
| Service-Oriented Architecture | Multiple independent services | Applications request functionality through each service's API contract | Services communicate across a network to accomplish a larger goal |
Service-Oriented Architecture, or SOA, is an approach in which an application is composed of multiple independent services connected across a network rather than being a single self-contained monolith. SOA supports modularity, independent scaling, team autonomy, and service reusability. These benefits come with network dependencies and distributed system complexity.
Benefits and Trade-Offs
| SOA characteristic | What it enables | What it introduces |
|---|---|---|
| Independent services | Modularity and service reusability | Network dependencies |
| Separate service ownership | Team autonomy | Distributed system complexity |
| Separate service development | Independent development, testing, and updating | Coordination through published API contracts |
SOA provides organizational and technical separation, but communication depends on contracts and a network.
The separation in SOA allows one service team to improve its service without changing unrelated service code. For example, the hotel service team can improve its search algorithm without touching flight search code, and a payment service can upgrade its security without affecting hotel availability checks.
Mistakes About APIs
Treating an API as the service's internal implementation
The API contract exposes the rules for requesting and receiving the service, while the service's internal implementation remains separate.
Fix:
Focus on the published request and response rules rather than the internal way the service performs its work.Thinking that several services automatically form one application
In the travel example, the application acts as the orchestrator. It knows which services to call, in what order, and how to combine their responses.
Fix:
Trace the coordinating application and the API contract used at each service boundary.Ignoring the response rules
An API contract governs requests and responses. The response typically includes data in a standardized format and a status code indicating success or failure.
Fix:
Examine both the request requirements and the response format and status information.Assuming SOA removes all complexity
SOA introduces network dependencies and distributed system complexity even while providing modularity and independent service development.
Fix:
Recognize both the modular benefits and the communication costs of service-oriented design.
Contract Tracing Practice
A travel application needs hotel availability from a hotel service. Describe the interaction in order: what the application sends, what the service checks, what the service returns, and what the application does with the response.
Hints
- Include the requested functionality and any parameters that customize the request.
- Mention authentication credentials only as a possibility if the service requires them.
- Include returned data, a standardized response format such as JSON or XML, and a status code.
- End by explaining that the application parses the response and uses the data to continue its work.
Classify this design: an application contains all of its functionality inside one self-contained program, with no separate services connected across a network. Is this closer to a monolithic design or to SOA? Explain which structural detail supports your answer.
Hints
- Look for whether the application is self-contained.
- SOA is composed of multiple independent services connected across a network.
Key Takeaways
- An API is a published contract between applications that specifies the rules for requesting and receiving services.
- A request follows the service's contract and may contain the requested task, parameters, and authentication credentials if required.
- A response typically contains requested data in a standardized format such as JSON or XML, together with a status code indicating success or failure.
- SOA composes an application from independent services connected across a network, while a monolithic design is a single self-contained application.
- API contracts allow services to be developed, tested, updated, and reused independently, while network dependencies and distributed system complexity remain important trade-offs.
Key Takeaways
- An API is a published contract that defines how applications request and receive services.
- The contract covers request information, possible authentication requirements, response data, response formats, and status information.
- In SOA, an orchestrating application combines the work of independent services connected across a network.
- SOA enables modularity, independent scaling, team autonomy, and service reuse, but introduces network dependencies and distributed system complexity.