Exchanging Data Across the Web: XML, JSON, and APIs
An API is a published contract between applications that specifies the exact rules for requesting and receiving services.
One Application, Many Services
A single application can depend on several separate services. A travel booking application, for example, may use one service for flight data, another for hotel inventory, and a third for payment processing. The user experiences one combined application, but behind that experience, separate services communicate across a network.
Following a Single Request
What do you think happens?
An application needs information from an external service. What must happen before the service returns a response?
Reveal answer
Answer: The application sends a request that follows the service's published API rules.
The application sends a request containing what it is asking for, any parameters that customize the request, and authentication credentials if required. The service validates the request against its API contract before processing it.
An Application Program Interface, or API, is a published contract between applications. The contract specifies the exact rules for requesting and receiving services. This means the requesting application does not need to understand the service's internal implementation. It needs to know how to form a valid request and how to interpret the response.
The Contract Behind the Exchange
An API is a published contract between applications that specifies the exact rules for requesting and receiving services.
A service's published contract makes integration possible because both sides can follow shared rules. The requesting application knows what it is asking for and which parameters may customize the request. If authentication is required, the request includes the required credentials. The receiving service validates the request against the contract, processes it, and returns a response. The response commonly contains requested data in a standardized format such as JSON or XML, together with a status code showing whether the request succeeded or failed.
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 services connected across a network |
| 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 |
Tracing the Travel Example
A Travel Booking Request
How can one travel application use separate services to support a larger booking goal?
Identify the services: The application uses specialized services for flight data, hotel inventory, payment processing, and user accounts.
Act as the orchestrator: The travel application knows which services to call, in what order, and how to combine their responses into one cohesive user experience.
Follow each contract: Each service publishes an API contract that tells the application how to make requests and what format the responses will use.
Keep responsibilities separate: Each service can be developed, tested, and updated independently. For example, a hotel service team can improve its search algorithm without changing flight search code.
The application composes separate networked services through their API contracts instead of implementing every responsibility inside one self-contained application.
The important movement is not only the data itself. The application must also coordinate the services: it decides which service to call, follows each service's published rules, receives each response, and combines the results. The services remain independent, while the orchestrating application creates the larger experience.
Mistakes in Service Integration
Treating an API as the service's internal implementation
An API contract allows an application to request functionality without needing to understand the service's internal implementation.
Fix:
Focus on the published request rules and the response rules.Assuming SOA is just one large application with several features
SOA is defined by multiple independent services connected across a network.
Fix:
Check whether separate services communicate across a network through their API contracts.Ignoring the response format
The response uses a standardized format such as JSON or XML, and the application must parse that response before using the data.
Fix:
Use the response format specified by the service's contract.Ignoring the status code
The response includes a status code indicating whether the request succeeded or failed.
Fix:
Interpret the status code as part of processing the response.
Practice the Trace
A booking application needs hotel availability from an external hotel service. Describe the exchange in order: what the application sends, what the hotel service checks, what the service returns, and what the application does with the response.
Hints
- Include the information being requested and any parameters that customize the request.
- Remember that authentication credentials may be required.
- Mention validation against the API contract, a response in JSON or XML, a status code, and parsing the response.
- An API is a published contract between applications. It defines the rules for requesting and receiving a service. In a service-oriented architecture, multiple independent services communicate across a network and contribute to one larger application. Each service can hide its internal implementation behind its API contract. A request follows the published rules, the service validates and processes it, and the response returns data in a standardized format such as JSON or XML together with a status code. SOA supports modularity and independent service work, but it also introduces network dependencies and distributed system complexity.
Key Takeaways
- An API is a published contract that specifies how applications request and receive services.
- SOA composes an application from multiple independent services connected across a network.
- Each service can expose functionality through an API without revealing its internal implementation.
- Requests follow published rules, while responses commonly contain JSON or XML data and a status code.
- SOA supports modularity and independent service work, but network dependencies add distributed system complexity.