JSON: A Lightweight Data Format
The same pattern applies to other services. A payment processor can expose transaction verification, and a social media platform can expose selected data-sharing capabilities, while each provider controls what remains internal.
Why Applications Need APIs
Modern software rarely works in isolation. A weather application may need data from a meteorological service, a payment processor may need to verify a transaction with a bank, and a social media platform may need to share data with an analytics tool. In each case, one application needs a controlled way to use a service provided by another application.
An API, or application programming interface, is an application-to-application contract. It publishes the rules for accessing services that one program provides for use by other programs. The contract lets applications exchange requests and responses without requiring the consumer to understand the provider's internal implementation.
A useful analogy is a restaurant menu. The restaurant is the service provider, the menu is the API, and the customer is the service consumer. The menu describes what can be ordered and how to order it, while the kitchen's internal operations remain hidden. In the same way, an API exposes selected services without exposing the provider's entire internal system.
Following a Request
- 1The consumer application sends a request to the provider application.
- 2The request identifies the service needed and supplies any necessary parameters.
- 3The provider processes the request according to the API's rules.
- 4The provider sends a response containing requested data or confirmation of an action.
- 5The consumer uses the response without needing to know how the provider stores or processes its data internally.
This request-and-response cycle takes place over HTTP, the transport protocol that also powers the web. The API contract determines what the consumer may request and what kind of response it should expect.
The Three Parts of the Contract
Every API involves three essential elements. The service provider is the application offering the service. The API specification is the published set of rules. The service consumer is the application using the service. The provider documents available services, accepted parameters, request data formats, and response formats. The consumer follows that documentation when making requests.
HTTP, JSON, and XML
HTTP and JSON have different roles in an API exchange. HTTP provides the transport used to move the request and response between applications. JSON provides one format for representing the data being exchanged. XML is another data representation format. Therefore, HTTP describes how the exchange travels, while JSON or XML describes how the exchanged data is represented.
A Weather Service Scenario
Requesting Current Weather
A weather application needs the current temperature from a meteorological service. How does the API relationship work?
- 1Identify the provider
The meteorological service is the service provider because it offers weather data.
- 2Read the specification
The weather application, acting as the consumer, follows the published API rules to learn which service to request, which parameters are needed, and what response format to expect.
- 3Send the request
The consumer sends a request through HTTP, specifying the weather service it wants and any necessary parameters.
- 4Receive the response
The provider processes the request and returns the requested weather data. That data may be represented using JSON or XML according to the API contract.
- 5Use the result
The weather application uses the response without needing to know how the provider collects, stores, processes, or analyzes its data internally.
The API allows the weather application to use a selected service while the meteorological provider keeps its internal systems behind the API boundary.
The important point is not the internal weather system. The consumer only needs the published interface: what service is available, how to request it, what parameters are needed, and how the response is represented.
The same pattern applies to other services. A payment processor can expose transaction verification, and a social media platform can expose selected data-sharing capabilities, while each provider controls what remains internal.
Mistakes Beginners Make
Common mistake Treating JSON as the API itself.
What it looks likeAssuming that choosing JSON automatically defines which service can be requested.
Why it failsJSON is a data representation format. The API contract defines the available services, parameters, and expected responses.
Do this insteadSeparate the API rules from the format used to represent exchanged data.
Common mistake Confusing HTTP with the data format.
What it looks likeDescribing HTTP as the format in which a response's data is written.
Why it failsHTTP is the transport protocol used for the exchange, while JSON or XML represents the data.
Do this insteadRemember: HTTP transports the exchange; JSON or XML represents the data.
Common mistake Expecting the consumer to understand the provider's internal system.
What it looks likeThinking a weather application must know how the meteorological service collects or stores weather information.
Why it failsThe API acts as an abstraction boundary and hides internal complexity.
Do this insteadUse the published API specification rather than depending on internal implementation details.
Common mistake Assuming an API exposes everything a provider can do.
What it looks likeTreating access to one published service as unrestricted access to the provider's application.
Why it failsAn API exposes only the specific services and capabilities the provider chooses to publish.
Do this insteadTreat the API as a controlled boundary.
When reading about an API, identify four things separately: who provides the service, which rules are published, which application consumes the service, and whether HTTP, JSON, or XML is being discussed as transport or representation.
Check Your Understanding
A banking application asks another application to verify a transaction. Identify the service provider, the service consumer, the API specification, the transport protocol, and a possible data representation format.
Hints
- The provider is the application offering transaction verification.
- The consumer is the application requesting that service.
- The specification contains the published rules for making the request and interpreting the response.
- HTTP is the transport protocol, while JSON or XML can represent the exchanged data.
What do you think happens?
A consumer application receives a response represented in JSON. Does that response reveal how the provider stores its data internally?
Reveal answer
No, the API can expose a response format while hiding internal implementation details.
The API provides an abstraction boundary. The consumer needs to follow the contract and understand the response format, not the provider's internal data storage or processing.
What to Remember
- 1An API is an application-to-application contract that publishes rules for accessing services.
- 2The three participants are the service provider, the API specification, and the service consumer.
- 3A consumer sends a request, the provider processes it, and the provider returns data or confirmation.
- 4HTTP transports the API exchange, while JSON or XML represents the exchanged data.
- 5An API hides internal complexity and exposes only selected capabilities.
At a glance
- An API defines a controlled relationship between applications.
- The provider publishes rules that tell consumers how to request services and interpret responses.
- HTTP is used for transport, while JSON and XML are used to represent exchanged data.
- The API boundary protects internal complexity and limits access to explicitly exposed services.