Building Your First API Request
An API is an application-to-application contract that publishes rules for accessing services provided by one program for use by other programs.
A Request Is a Conversation
Modern software rarely works in isolation. A weather application may need information from a meteorological service, while a payment processor may need to verify a transaction with a bank. An API gives one application a controlled, standardized way to request a service from another application and receive a response.
The important idea is that the consumer does not directly control the provider's internal systems. It follows the API's published rules, sends a request for an available service, and interprets the response in the format promised by the contract. The API creates a boundary between the two applications.
The Three Parts of the Contract
An API is an application-to-application contract that publishes rules for accessing services provided by one program for use by other programs.
Every API contract involves three essential elements. The service provider is the application offering a capability. The API specification is the published set of rules that describes how that capability can be accessed. The service consumer is the application that uses the capability. The provider maintains the API, the specification describes the permitted interaction, and the consumer follows those rules.
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 consumer. The menu lists what can be requested and the rules for ordering, but it does not reveal how the kitchen operates internally. In the same way, an API exposes selected services without exposing the provider's internal workings.
From Service to Response
Using an API follows a predictable cycle. First, the consumer application identifies the service it wants and supplies any necessary parameters. Next, it sends a request to the provider application according to the API's rules. The provider receives and processes the request. Finally, the provider sends a response containing the requested data or confirmation that an action occurred.
This boundary is an abstraction. A weather service may contain extensive code for collecting, storing, processing, and analyzing information, but its API can expose only selected services such as current temperature, forecasts, or historical data. A consumer needs to understand the published access rules and response format, not the provider's entire internal implementation.
Transport and Data Formats
An API request has two different concerns. HTTP provides the transport used for the exchange between applications. XML or JSON represents the data being exchanged so that both applications can understand and parse it. HTTP answers how the communication travels; XML and JSON answer how the exchanged data is represented.
| Technology | Role in API communication |
|---|---|
| HTTP | Transports the request and response between applications. |
| XML | Represents exchanged data in a format applications can understand and parse. |
| JSON | Represents exchanged data in a format applications can understand and parse. |
The source identifies HTTP as the transport protocol and XML or JSON as data representation formats.
A Worked Request Trace
Requesting Weather Information
Trace what happens when a weather application asks a meteorological service for information through an API.
Identify the consumer: The weather application is the service consumer because it needs information provided by another application.
Choose the exposed service: The consumer chooses an available weather service, such as a service for current temperature or a forecast.
Follow the specification: The consumer follows the published API rules, including the required service parameters and the expected request and response data formats.
Send the request: The consumer sends its request to the provider application over HTTP.
Process the request: The provider receives the request and processes it according to the API contract without exposing its internal data collection, storage, or analysis systems.
Interpret the response: The provider returns the requested data in XML or JSON, and the consumer interprets that representation.
The weather application obtains the exposed service it needs without learning or directly accessing the provider's internal implementation.
Notice what this trace does not require. The consumer does not need to know how the weather provider gathers information, stores it, or performs analysis. It needs the API contract: which service is available, which parameters are required, how to make the request, and how to interpret the returned data.
Mistakes Beginners Make
Treating an API as the provider application's internal implementation.
An API is a boundary that exposes selected services while hiding internal complexity.
Fix:
Focus on the published services, parameters, request format, and response format defined by the API specification.Confusing HTTP with XML or JSON.
HTTP is the transport protocol, while XML and JSON represent the data exchanged between applications.
Fix:
Describe HTTP as how the request and response travel, and XML or JSON as how their data is represented.Thinking that an API is only a response containing data.
The API cycle includes a request, provider processing, and a response, all governed by the contract.
Fix:
Trace both directions: the consumer sends a compliant request, and the provider returns data or confirmation.Assuming that using an API gives unrestricted access to the provider.
APIs protect internal systems by exposing only the services explicitly made available.
Fix:
Treat the published API specification as the limit of the consumer's permitted interaction.
Practice the Trace
A payment processor needs to verify a transaction with a bank. Identify the service consumer, the service provider, the API specification, the transport technology, and the possible data representation formats. Then describe the request-and-response cycle in order.
Hints
- The consumer is the application asking another application for a service.
- The provider is the application offering the transaction-verification capability.
- The API specification contains the rules for accessing the service.
- HTTP transports the exchange, while XML or JSON can represent the exchanged data.
When learning any API, begin with its contract rather than its internal implementation. Identify the available service, required parameters, request data format, response data format, and the boundary that controls access.
Key Takeaways
- An API is an application-to-application contract that publishes rules for accessing services.
- The three parts of the contract are the service provider, the API specification, and the service consumer.
- A consumer sends a request, the provider processes it according to the rules, and the provider returns data or confirmation.
- HTTP transports API communication, while XML and JSON represent exchanged data.
- The API boundary hides internal complexity and exposes only the services the provider chooses to make available.
Key Takeaways
- An API defines a controlled agreement between applications.
- The provider exposes selected services through published rules, and the consumer follows those rules.
- HTTP carries the exchange, while XML or JSON represents the data.
- The request-and-response cycle lets applications cooperate without exposing internal implementation details.