HTTP and Web Communication Protocols
An API is a published contract between applications that specifies the exact rules for requesting and receiving services.
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?
Choose a service: The travel application identifies the specialized service it needs, such as a flight data service, hotel service, or payment service.
Build 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.
Validate 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.
Return 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.
Continue 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 |
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
Treating an API as the service's internal implementation.
An API contract specifies the rules for requesting and receiving a service; the requesting application does not need to understand the service's internal implementation.
Fix:
Focus on the published request rules and response format.Describing SOA as one self-contained application.
SOA composes multiple independent services connected across a network.
Fix:
Check whether separate services communicate across a network and maintain their own API contracts.Ignoring response status information.
A response includes a status code that indicates whether the request succeeded or failed.
Fix:
Interpret both the returned data and the status code before continuing application work.Assuming every request has the same contents.
The request includes specific information, including the requested operation, parameters, and authentication credentials if required.
Fix:
Construct 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.
- An 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.