HTTP: The Protocol Behind Web Communication
An API is an application-to-application contract that publishes rules for accessing services provided by one program for use by other programs.
From Isolated Programs to Connected Services
Modern software rarely works in isolation. A weather application may need data from a meteorological service, a payment processor may need to verify transactions with a bank, and a social media platform may need to share user data with analytics tools. In each case, one application needs a controlled way to use capabilities provided by another application.
An application programming interface, or API, provides that controlled connection. It is an application-to-application contract that publishes rules for accessing services provided by one program for use by other programs. The API does not expose the provider's entire internal system. Instead, it defines the specific services that consumers may request and the form those requests and responses should take.
The Three Participants in an API Contract
Every API involves three essential elements. The service provider is the application offering a service. The published API specification contains the rules for using that service. The service consumer is the application that follows those rules to request the service.
| Participant | Role in the contract |
|---|---|
| Service provider | Creates and maintains the API and offers services through it |
| API specification | Documents available endpoints, accepted parameters, request data format, and response data format |
| Service consumer | Reads the specification and writes code that follows its rules |
The three participants that make an API contract usable
The source compares an API with a restaurant menu. The restaurant represents the service provider, the menu represents the API, and the customer represents the service consumer. The menu lists what can be ordered and the rules for ordering, while the kitchen's internal operations remain hidden. In the same way, an API tells a consumer what services are available without requiring the consumer to understand the provider's internal workings.
Following a Request and Response
When an application uses an API, the interaction follows a predictable cycle. The consumer sends a request to the provider, identifying the service it wants and supplying any necessary parameters. The provider receives the request, processes it according to the API's rules, and sends back a response containing the requested data or confirmation that an action occurred.
A Weather Data Request
Trace what happens when a weather application needs data from a meteorological service.
Choose a service: The weather application acts as the service consumer and determines that it needs data provided by the meteorological service.
Follow the contract: The consumer uses the API specification to identify the available service and provide any necessary parameters in the expected format.
Send the request: The consumer sends its request to the provider application using HTTP as the transport protocol.
Process the request: The meteorological service receives the request and processes it according to the API's rules.
Return the response: The provider sends back the requested data or a confirmation in the response format described by the API.
The weather application can use the meteorological service without knowing how that service collects, stores, or processes its internal data.
Transport and Data Representation
HTTP, XML, and JSON have related but different roles in API communication. HTTP is the transport protocol: it carries the communication between the consumer and provider. XML and JSON are data representation formats: they represent the information being exchanged so that both applications can understand and parse it.
| Technology | Role in API communication | What it helps applications do |
|---|---|---|
| HTTP | Transport protocol | Carry requests and responses between applications |
| XML | Data representation format | Represent exchanged data in a form both applications can understand and parse |
| JSON | Data representation format | Represent exchanged data in a form both applications can understand and parse |
Why the Boundary Matters
An API is an abstraction boundary between an application's internal complexity and the outside world. A weather service may contain extensive code for collecting, storing, processing, and analyzing data, but its API can expose only selected services, such as obtaining current temperature, receiving a forecast, or retrieving historical data.
- The provider's internal systems are protected because the consumer can access only functionality explicitly exposed through the API.
- The provider can change its internal implementation without breaking consumers as long as the API contract remains the same.
- The consumer's code is simpler because it needs to learn only the API rather than the provider's entire internal system.
A mobile application may use APIs from payment processors, mapping services, social networks, and analytics platforms. Each service can expose selected capabilities through its API while keeping its internal implementation separate from the mobile application's code.
Mistakes Beginners Make
Defining an API as the provider's internal implementation
An API hides internal complexity and exposes only the services and rules that consumers need.
Fix:
Treat the API as the published boundary and contract, not as the complete system behind it.Treating the API as only the response data
The API contract also includes available services, accepted parameters, request data format, and response format.
Fix:
Think of the API as the complete set of published rules for requesting and receiving a service.Confusing HTTP with XML or JSON
HTTP transports the communication, while XML and JSON represent the data exchanged.
Fix:
Remember the division of labor: HTTP carries the exchange; XML or JSON represents its data.Assuming that an API gives unrestricted access
APIs act as protective boundaries and expose only specific services.
Fix:
Use only the capabilities and formats published in the API specification.
Check Your Understanding
A banking application needs a transaction verification service from another application. Explain the roles of the service provider, API specification, and service consumer. Then identify which technology transports the request and response, and which technologies can represent the exchanged data.
Hints
- The application offering transaction verification is the provider.
- The rules describing available services, parameters, and data formats form the API specification.
- The application requesting verification is the consumer.
- HTTP transports the communication; XML or JSON can represent the exchanged data.
- An API is an application-to-application contract that publishes rules for accessing services. The provider offers the service, the API specification defines the rules, and the consumer follows those rules. A consumer sends a request, the provider processes it, and the provider returns data or confirmation. HTTP transports this request-response communication, while XML and JSON represent the exchanged data. The API boundary hides internal complexity, protects systems, and lets providers change internal implementations without breaking consumers when the contract remains the same.
Key Takeaways
- An API is an application-to-application contract for accessing services.
- The provider, published API specification, and consumer are the three participants in the contract.
- API communication follows a request-response cycle between applications.
- HTTP transports API communication, while XML and JSON represent exchanged data.
- APIs provide an abstraction boundary that protects internal systems and simplifies consumers.