Exchanging Data Across the Web: XML, JSON, and APIs
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.
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
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 |
The central structural difference is whether the application is one self-contained unit or a composition of independent networked services.
Tracing the Travel Example
A Travel Booking Request
How can one travel application use separate services to support a larger booking goal?
- 1Identify the services
The application uses specialized services for flight data, hotel inventory, payment processing, and user accounts.
- 2Act 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.
- 3Follow each contract
Each service publishes an API contract that tells the application how to make requests and what format the responses will use.
- 4Keep 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
Common mistake Treating an API as the service's internal implementation
What it looks likeAssuming the client must understand how the service performs its work internally
Why it failsAn API contract allows an application to request functionality without needing to understand the service's internal implementation.
Do this insteadFocus on the published request rules and the response rules.
Common mistake Assuming SOA is just one large application with several features
What it looks likeDescribing a single self-contained application as service-oriented because it has separate features
Why it failsSOA is defined by multiple independent services connected across a network.
Do this insteadCheck whether separate services communicate across a network through their API contracts.
Common mistake Ignoring the response format
What it looks likeUsing a service response without accounting for whether its data is returned as JSON or XML
Why it failsThe response uses a standardized format such as JSON or XML, and the application must parse that response before using the data.
Do this insteadUse the response format specified by the service's contract.
Common mistake Ignoring the status code
What it looks likeUsing returned data without checking whether the request succeeded or failed
Why it failsThe response includes a status code indicating whether the request succeeded or failed.
Do this insteadInterpret 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.
- 1An 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.