JSON and XML: Data Formats for Web Services
The round trip is what makes the service a web service: a client reaches the service remotely through HTTP, rather than calling it only inside the application's local environment.
From API to Web Service
An application's API defines the contract for how other software can interact with it. That API may contain many services, but those services are not automatically available across a network. A web service is created when an application selects services from its API and makes them available over the web, typically through HTTP. The key idea is exposure: a web service is an API capability prepared for remote access.
The HTTP Request Round Trip
A remote interaction begins with a client application. The client may run on a user's machine, a mobile device, or another server. It sends an HTTP request to a specific endpoint, which is a URL pointing to a particular service within the web application. The request travels across the network to the web server. The server routes it to the correct service in the application's API, the service processes it, and the server sends a response back over HTTP.
The round trip is what makes the service a web service: a client reaches the service remotely through HTTP, rather than calling it only inside the application's local environment.
Local Calls and Remote Access
A local API and a web service can both define valid requests and expected responses, but they differ in how those interactions are delivered and who can reach them. A local API may describe communication between modules in one application. For example, a user interface module can call functions in a data-processing module. Those modules run on the same machine and communicate through direct function calls or local inter-process communication.
A web service is designed for remote access. It is exposed over HTTP, so clients across a network can reach it by sending requests to its endpoints. Therefore, the API contract may be similar in both situations, while the delivery mechanism and accessibility are fundamentally different.
| Characteristic | Local API | Web service |
|---|---|---|
| Typical scope | Modules within a single application | Clients across a network |
| Access method | Direct function calls or local inter-process communication | HTTP requests to endpoints |
| Location of communicating components | Same machine or local application environment | Client and server connected through a network |
| API contract | Defines valid interactions and expected responses | Defines valid interactions and expected responses |
The contract can be similar; the communication mechanism and accessibility differ.
Why Applications Expose Services
An application creates web services when it wants other software to use selected functionality without requiring that software to run the same code or be installed on the same machine. A central server can provide functionality to many clients over a network. Those clients can include mobile applications, web dashboards, external partners, and other systems.
This arrangement supports distributed systems and microservices architectures. It also allows third-party developers to build on an application's functionality without receiving direct access to the application's internal code. The application exposes a selected part of its API as a network-accessible service while keeping the implementation on the server.
Weather Service Walkthrough
Consider a weather application that collects temperature, humidity, and forecast data. Its internal API includes services named GetCurrentTemperature, GetForecast, and GetHistoricalData. These services exist in the application's code. If the developers expose selected services over HTTP, other applications can use them remotely.
Requesting the Current Temperature
Trace what happens when a mobile application requests the current temperature for Seattle.
- 1Select the service
The weather application exposes its GetCurrentTemperature service through an HTTP endpoint.
- 2Send the request
The mobile application sends an HTTP request to https://weather-service.example.com/api/current-temperature?city=Seattle.
- 3Route the request
The web server receives the request and routes it to the correct service within the weather application's API.
- 4Process the request
The GetCurrentTemperature service processes the request for Seattle.
- 5Return the response
The web service sends data back over HTTP. The source example identifies this response as JSON data containing the current temperature.
The service logic remains part of the weather application, but exposing it over HTTP allows a mobile app and other clients with network access to consume it.
JSON and XML in This Context
JSON and XML are named as data formats for web services in this topic. The source example specifically describes the weather service's response as JSON data containing the current temperature. This shows the role of a data format in the request cycle: after the service processes a request, the returned information must be represented as response data that the client can receive.
The central lesson is separate from the choice of format. JSON or XML describes how returned data is represented, while web service describes how selected application functionality is exposed and reached through HTTP. A response format does not by itself make an API a web service; network access through HTTP is the defining feature emphasized here.
Common Misunderstandings
Common mistake Treating every API as a web service
What it looks likeA user interface module calls a data-processing module through a local function call.
Why it failsAn API can be local to an application and may not be reachable across a network.
Do this insteadCall it a web service only when selected API services are intentionally exposed for remote access, typically through HTTP.
Common mistake Assuming that a response format creates the web service
What it looks likeA service returns JSON, so the response format is treated as the definition of the service.
Why it failsThe defining feature is remote accessibility through HTTP, not merely the representation of the returned data.
Do this insteadIdentify the HTTP endpoint and remote request flow first; then identify the response format.
Common mistake Assuming the entire application API must be exposed
What it looks likeThe presence of one public endpoint is interpreted as making every internal service available.
Why it failsA web service is a set of selected services from an application's API.
Do this insteadAsk which specific API services the application intentionally made available over the web.
Common mistake Forgetting the server-side routing step
What it looks likeThe client is described as calling the internal service directly across the network.
Why it failsThe request first reaches the web server, which routes it to the correct service within the application's API.
Do this insteadTrace the request as client, HTTP endpoint, web server, API service, and HTTP response.
Check Your Understanding
An application has an internal service called GetForecast. A mobile application on another device sends an HTTP request to an endpoint that exposes this service. Explain why GetForecast is now a web service, and identify the steps the request follows before the response reaches the mobile application.
Hints
- Start by identifying where the service originally exists.
- Look for the change in accessibility and communication method.
- Include the web server's routing role in your trace.
What do you think happens?
A service returns JSON data, but a client can use it only through a local function call inside the same application. Is it automatically a web service?
Reveal answer
No, because it is not exposed for remote HTTP access
The source distinguishes a local API from a web service by accessibility and delivery mechanism. A web service is an API service intentionally made available to remote clients through HTTP.
Key Takeaways
- 1An application's API defines how other software can interact with the application.
- 2A web service is a selected set of API services exposed for remote access, typically through HTTP.
- 3A remote request travels from a client to an endpoint, reaches the web server, is routed to the correct API service, and returns as an HTTP response.
- 4A local API serves components within a local application environment, while a web service serves clients across a network.
- 5JSON and XML are data formats associated with web services; the supplied example specifically identifies JSON as the response format.
At a glance
- A web service is an intentionally exposed part of an application's API that remote clients can access through HTTP.
- The request path is client, endpoint, web server, API service, and HTTP response.
- A local API and a web service may describe similar interactions, but they differ in communication mechanism and accessibility.
- Applications expose web services so many clients can use central functionality without sharing the application's internal code.
- JSON and XML describe data formats in this context; the source provides JSON as the concrete response example.