JSON: A Lightweight Data Format
An API is an application-to-application contract that publishes rules for accessing services provided by one program for use by other programs.
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
- The consumer application sends a request to the provider application.
- The request identifies the service needed and supplies any necessary parameters.
- The provider processes the request according to the API's rules.
- The provider sends a response containing requested data or confirmation of an action.
- The 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?
Identify the provider: The meteorological service is the service provider because it offers weather data.
Read 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.
Send the request: The consumer sends a request through HTTP, specifying the weather service it wants and any necessary parameters.
Receive 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.
Use 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
Treating JSON as the API itself.
JSON is a data representation format. The API contract defines the available services, parameters, and expected responses.
Fix:
Separate the API rules from the format used to represent exchanged data.Confusing HTTP with the data format.
HTTP is the transport protocol used for the exchange, while JSON or XML represents the data.
Fix:
Remember: HTTP transports the exchange; JSON or XML represents the data.Expecting the consumer to understand the provider's internal system.
The API acts as an abstraction boundary and hides internal complexity.
Fix:
Use the published API specification rather than depending on internal implementation details.Assuming an API exposes everything a provider can do.
An API exposes only the specific services and capabilities the provider chooses to publish.
Fix:
Treat 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
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
- An API is an application-to-application contract that publishes rules for accessing services.
- The three participants are the service provider, the API specification, and the service consumer.
- A consumer sends a request, the provider processes it, and the provider returns data or confirmation.
- HTTP transports the API exchange, while JSON or XML represents the exchanged data.
- An API hides internal complexity and exposes only selected capabilities.
Key Takeaways
- 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.