Error Handling and API Response Codes
An API is a published contract between applications that specifies the exact rules for requesting and receiving services.
One Request, Several Rules
When one application uses a service owned by another application, the two sides need more than a network connection. They need shared expectations. The requesting application must know what information to send, the service must know how to interpret that request, and the requesting application must know how to interpret the response. An Application Program Interface, or API, provides those expectations as a published contract.
An API is a published contract between applications that specifies the exact rules for requesting and receiving services.
Tracing a Service Request
A service interaction can be understood as a sequence of state changes. First, the application identifies the functionality it needs. It then sends a request that follows the service's published rules. That request contains what is being requested, parameters that customize the request, and authentication credentials if required. The service validates the request against its API contract, processes it, and sends back a response. The response typically contains requested data in a standardized format such as JSON or XML, together with a status code indicating whether the request succeeded or failed. Finally, the application parses the response and uses the data to continue its work.
A Travel Booking Request
A travel booking application needs to combine flight data, hotel availability, payment processing, and user account functionality.
Choose services: The application acts as an orchestrator and identifies the specialized services needed for the larger travel-booking goal.
Follow contracts: The application sends each request according to the relevant service's published API contract, including the required request information and any parameters.
Receive responses: Each service returns a response in a standardized format, together with a status code that indicates success or failure.
Combine results: The application parses the responses and combines the returned data into a cohesive user experience.
Separate services contribute specialized functionality while the travel application coordinates their requests and responses.
Monoliths and Service-Oriented Systems
A monolithic application is described in the source material as a single self-contained application. A Service-Oriented Architecture, or SOA, takes a different approach: an application is composed of multiple independent services connected across a network. Each service provides specialized functionality through its own API contract.
| Design | Structure | How functionality is accessed | Important consequence |
|---|---|---|---|
| Monolithic application | Single self-contained application | Functionality is contained within that application | The application is not described as a collection of independent network-connected services |
| Service-Oriented Architecture | Multiple independent services connected across a network | Applications request functionality through each service's API contract | The design supports modularity, independent scaling, team autonomy, and service reusability |
Reading Success and Failure
A response is not only a container for returned data. It also includes a status code indicating whether the request succeeded or failed. The application should therefore inspect the response before using its data. A successful response can provide data for the next stage of the application. A failed response signals that the normal path did not complete, so the application must handle that result rather than treating it as the expected data.
A response can contain a standardized data format such as JSON or XML and still indicate failure through its status code. The application must consider both parts of the response: the returned format and the success-or-failure indication.
Contracts as Integration Rules
An API contract makes integration possible because both sides can work from the same published rules. 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 service can then maintain its own implementation while exposing the agreed interface.
The contract separates what a service offers from how the service implements it. This lets an application request functionality without needing to understand the service's internal implementation.
Mistakes in Error Handling
Treating an API as merely a network connection
The service validates requests against its API contract. A connection alone does not define what information the request must contain or how the response should be interpreted.
Fix:
Use the published API contract as the source of truth for request information, parameters, authentication requirements, response format, and status-code meaning.Ignoring the response status code
The response includes a status code specifically to indicate whether the request succeeded or failed.
Fix:
Inspect the status indication before treating returned data as the successful result of the request.Assuming every service exposes the same internal implementation
An API contract allows applications to request functionality without understanding the service's internal implementation.
Fix:
Depend on the published contract rather than on undocumented internal details.Assuming SOA removes all complexity
SOA introduces network dependencies and distributed system complexity even while providing modularity and service reusability.
Fix:
Treat service communication and response handling as part of the architecture.
Practice the Trace
A travel application requests hotel availability from a specialized hotel service. Explain the sequence from request to application result. Include the API contract, request validation, response data, status code, and the application's next action.
Hints
- Begin with the rules published by the hotel service.
- Identify what the service does before returning a response.
- Explain why the application must inspect the status code before using the returned data.
Tracing the Hotel Service
Complete the request trace for the travel application when it needs hotel availability.
Published contract: The hotel service publishes the rules for requesting hotel availability and for receiving the response.
Request: The travel application sends a request that follows those rules and includes the information and parameters required by the service.
Validation and processing: The hotel service validates the request against its API contract and processes it.
Response: The hotel service sends back data in a standardized format together with a status code indicating success or failure.
Application action: The travel application parses the response and either uses the returned data in its larger booking work or handles the failure indication instead of treating it as a normal successful result.
The contract gives both applications a shared procedure for requesting, responding, and deciding what to do next.
Key Takeaways
- An API is a published contract that defines the rules for requesting and receiving services.
- SOA composes an application from independent services connected across a network, unlike a single self-contained monolith.
- Each service can maintain its own API contract and internal implementation while other applications request its functionality.
- A service response includes returned data and a status code indicating success or failure.
- Effective integration depends on following the published contract and handling the response indication before continuing application work.
Key Takeaways
- An API is a published contract between applications, not merely a connection between them.
- Service-Oriented Architecture uses independent network-connected services to compose a larger application.
- A request follows the service contract, is validated and processed, and produces a response with data and a status code.
- Applications must distinguish a success indication from a failure indication before using the response as normal data.
- Published contracts enable integration while allowing services to preserve independent implementations.