HTTP and Web Communication Protocols
A web application can accomplish a larger goal by communicating with several specialized services instead of containing every capability inside one program.
From One Application to Many Services
A web application can accomplish a larger goal by communicating with several specialized services instead of containing every capability inside one program. The key question is how independently built applications know what they may request, how to request it, and how to interpret the result. An Application Programming Interface, or API, answers that question by publishing a contract between applications.
The API Contract
An API is a published contract between applications that specifies the exact rules for requesting and receiving services.
The contract is the boundary between what a service does internally and what another application needs to know. A requesting application does not need to understand the service's internal implementation. It needs to follow the published rules: identify what it is asking for, provide any required parameters, include authentication credentials if required, and understand the format and status information returned by the service.
Tracing a Service Request
A Travel Booking Request
How does a travel application use an external service while keeping the service's internal implementation separate?
- 1Choose a service
The travel application identifies the specialized service it needs, such as a flight data service, hotel service, or payment service.
- 2Build the request
The application follows the service's published API contract. The request states what is being requested, includes parameters that customize the request, and includes authentication credentials if the service requires them.
- 3Validate and process
The service receives the request, validates it against its API contract, and processes it without requiring the requesting application to understand the service's internal implementation.
- 4Return the response
The service sends back requested data in a standardized format such as JSON or XML, together with a status code indicating whether the request succeeded or failed.
- 5Continue the application work
The travel application parses the response and uses the data as part of a larger user experience.
The API contract coordinates the exchange: the requesting application follows the published request rules, and the service returns data and status information in the published response form.
SOA and Monolithic Design
| Design | Structure | How functionality is accessed | Important consequence |
|---|---|---|---|
| Monolithic application | A single self-contained application | Functionality is contained within that application | The application is not composed of multiple independent networked services |
| Service-Oriented Architecture | Multiple independent services connected across a network | Applications request functionality through each service's API contract | Services can be developed, tested, and updated independently |
The central distinction is whether the application is one self-contained unit or a composition of independent services.
In a Service-Oriented Architecture, each service maintains its own API contract. This allows an application to request functionality without understanding how that service implements its work. The larger application acts as an orchestrator: it knows which services to call, in what order, and how to combine their responses into a cohesive user experience.
Why Published Rules Matter
Published rules make integration possible because independently built applications can coordinate without sharing their internal implementations. A service publishes what a request must contain and what a response will contain. The requesting application can then construct a valid request, interpret standardized returned data, and use the status code to determine whether the request succeeded or failed.
Common Integration Mistakes
Common mistake Treating an API as the service's internal implementation.
What it looks likeAssuming the requesting application must understand how a hotel service searches its inventory.
Why it failsAn API contract specifies the rules for requesting and receiving a service; the requesting application does not need to understand the service's internal implementation.
Do this insteadFocus on the published request rules and response format.
Common mistake Describing SOA as one self-contained application.
What it looks likeCalling a travel application service-oriented when all flight, hotel, and payment functionality is contained in one monolith.
Why it failsSOA composes multiple independent services connected across a network.
Do this insteadCheck whether separate services communicate across a network and maintain their own API contracts.
Common mistake Ignoring response status information.
What it looks likeUsing returned data without checking whether the service indicated success or failure.
Why it failsA response includes a status code that indicates whether the request succeeded or failed.
Do this insteadInterpret both the returned data and the status code before continuing application work.
Common mistake Assuming every request has the same contents.
What it looks likeLeaving out parameters or authentication credentials when the published contract requires them.
Why it failsThe request includes specific information, including the requested operation, parameters, and authentication credentials if required.
Do this insteadConstruct each request according to the service's published API contract.
Practice the Trace
A travel application needs flight data and hotel availability before it can present a booking option. Describe the request-and-response sequence for one of these services. Identify what the application asks for, what additional request information may be included, what the service validates, what the response contains, and how the application uses the response.
Hints
- Begin with the service's published API contract.
- Include the requested operation, parameters, and authentication credentials if required.
- Remember that the response includes data in a standardized format and a status code.
- 1An API is a published contract that defines how one application requests and receives a service from another. In SOA, an application is composed of independent services connected across a network, while a monolith is a single self-contained application. A request follows the service's contract, is validated and processed by the service, and receives data plus status information in the published response form. The larger application orchestrates these exchanges and combines the results into a cohesive user experience.
Key Takeaways
- An API is a published contract between applications.
- The contract defines the rules for requesting a service and interpreting its response.
- SOA composes multiple independent networked services, while a monolith is a single self-contained application.
- A service request may include the requested operation, parameters, and authentication credentials if required.
- Responses provide requested data in a standardized format such as JSON or XML, along with a status code.