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
- 1The application identifies the service functionality it needs.
- 2It creates a request that follows the service's published rules.
- 3The request includes what is being requested, parameters that customize the request, and authentication credentials if they are required.
- 4The service validates the request against its API contract.
- 5The service processes the request and sends a response.
- 6The 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?
- 1Identify specialized services
The application uses one service for flight data, another for hotel inventory, a third for payment processing, and another for user accounts.
- 2Follow each service contract
Each service publishes the rules for making requests and the format in which it returns responses.
- 3Coordinate the requests
The travel application acts as the orchestrator. It knows which services to call, in what order, and how to combine their responses.
- 4Build 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 |
SOA separates functionality into independent services, while a monolithic design keeps the application self-contained.
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
Common mistake Treating an API as the service's internal implementation
What it looks likeAssuming a client must understand how a payment service performs its processing before it can request payment functionality.
Why it failsThe API contract exposes the rules for requesting and receiving the service, while the service's internal implementation remains separate.
Do this insteadFocus on the published request and response rules rather than the internal way the service performs its work.
Common mistake Thinking that several services automatically form one application
What it looks likeListing flight, hotel, and payment services without identifying which application coordinates their requests and combines their responses.
Why it failsIn the travel example, the application acts as the orchestrator. It knows which services to call, in what order, and how to combine their responses.
Do this insteadTrace the coordinating application and the API contract used at each service boundary.
Common mistake Ignoring the response rules
What it looks likeConsidering only what an application sends and not what the service returns.
Why it failsAn API contract governs requests and responses. The response typically includes data in a standardized format and a status code indicating success or failure.
Do this insteadExamine both the request requirements and the response format and status information.
Common mistake Assuming SOA removes all complexity
What it looks likeExpecting independent services to behave like one local, self-contained application.
Why it failsSOA introduces network dependencies and distributed system complexity even while providing modularity and independent service development.
Do this insteadRecognize 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
- 1An API is a published contract between applications that specifies the rules for requesting and receiving services.
- 2A request follows the service's contract and may contain the requested task, parameters, and authentication credentials if required.
- 3A response typically contains requested data in a standardized format such as JSON or XML, together with a status code indicating success or failure.
- 4SOA composes an application from independent services connected across a network, while a monolithic design is a single self-contained application.
- 5API contracts allow services to be developed, tested, updated, and reused independently, while network dependencies and distributed system complexity remain important trade-offs.
At a glance
- 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.