Building and Consuming APIs
A web service is a set of services in an application's API that are made available over the web via HTTP.
From Internal Functionality to Network Access
An application can have an API even when no network is involved. Its API defines the contract for how other software can interact with it. When the application selects some of those services and makes them available over the web through HTTP, those services become a web service. The central idea is not simply that an API exists, but that selected API functionality has been intentionally exposed for remote access.
Following a Web Service Request
Consuming a web service means using its remotely accessible functionality. A client application 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 server hosting the application. The server routes the request to the correct service, that service processes it, and the server sends an HTTP response back to the client.
- A client application selects the service it needs.
- The client sends an HTTP request to that service's endpoint.
- The web server receives the request and routes it to the correct service.
- The service processes the request.
- The server returns a response over HTTP to the client.
API Contract and Web Service Boundary
An application's API is the broader contract describing how other software can interact with the application. That contract specifies which requests are valid and what responses to expect. A web service is a set of services from that API that has been exposed over the web, typically through HTTP. Therefore, a web service belongs to an application's API, but the entire API does not automatically become a web service.
Local Access and Remote Access
A local API can describe communication between modules within one application. For example, a user-interface module may 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 instead. Clients across a network can reach it by sending HTTP requests to its endpoints.
| Aspect | Local API | Web service |
|---|---|---|
| Where it is accessed | Within a single application or on the same machine | Across a network or the internet |
| Typical delivery mechanism | Direct function calls or local inter-process communication | HTTP requests and responses |
| Typical clients | Modules within the application | Remote applications, mobile apps, web dashboards, or other systems |
| Relationship to the API contract | Uses the application's interaction contract | Uses the same kind of contract while exposing selected services remotely |
Why Applications Expose Services
An application creates web services when it needs to make selected functionality available to clients that are not running the same code or located on the same machine. A central server can provide functionality to many different clients over a network. This allows external partners, mobile applications, and other systems to integrate with core functionality without receiving direct access to the application's internal code.
This arrangement supports distributed systems, microservices architectures, and third-party development because clients can use the service through its network interface rather than needing direct access to the server application's internal code.
Weather Data as a Web Service
Exposing Weather Application Services
A weather application already has internal services for current temperature, forecasts, and historical data. How can a mobile app use the current-temperature service?
Identify the internal API: The weather application's API includes services such as GetCurrentTemperature, GetForecast, and GetHistoricalData.
Select a service for exposure: Developers choose to make the current-temperature service available to other applications.
Expose the service over HTTP: The selected service is made available through an HTTP endpoint.
Send a request: A mobile application sends an HTTP request to https://weather-service.example.com/api/current-temperature?city=Seattle.
Return the result: The web service responds with JSON data containing the current temperature.
The service logic belongs to the weather application's API, while its HTTP endpoint makes that selected functionality available as a web service to clients with network access.
Notice the boundary in this example. The weather application had the service before it was exposed over HTTP. Making it reachable through an endpoint did not create a completely unrelated capability; it changed how that selected capability could be accessed. The same service logic can serve the application internally and, after exposure, be consumed by remote clients.
Mistakes About APIs and Web Services
Treating every API as a web service
Not all APIs are accessible across a network. A web service is specifically a set of API services intentionally exposed for network access, typically through HTTP.
Fix:
First ask whether remote clients can reach the service through HTTP. If the interaction remains local, it is a local API rather than a web service.Thinking that exposing an API means exposing the entire application
An application selects a set of services from its API to make available over the web.
Fix:
Separate the application's full API from the subset intentionally exposed as web services.Confusing an endpoint with the whole API
An endpoint points to a particular service within the web application, while the API defines the broader interaction contract.
Fix:
Treat the endpoint as an access point to a particular service within the larger API.Ignoring the request-and-response round trip
A remote client sends an HTTP request, the server routes it to a service, and an HTTP response returns to the client.
Fix:
Trace both directions: request from client to service and response from service back to client.
Check Your Understanding
An application's user-interface module calls a data-processing module through direct function calls on the same machine. The developers later expose one data-processing capability through an HTTP endpoint so a mobile application can use it. Classify each interaction as local API access or web service access, and explain what changed when the HTTP endpoint was added.
Hints
- Identify whether the communicating software is local or remote.
- Look for the delivery mechanism: direct function calls or HTTP.
- The API contract can remain related in both cases; focus on the change in accessibility.
- An application's API defines the contract for how other software can interact with it.
- A web service is a selected set of API services made available remotely, typically through HTTP.
- A client consumes a web service by sending an HTTP request to an endpoint and receiving an HTTP response.
- A local API serves software components within a local application or machine, while a web service serves clients across a network.
- Applications expose web services to let multiple remote clients use central functionality without direct access to internal code.
Key Takeaways
- An API is an interaction contract; a web service is a network-accessible subset of an application's API.
- HTTP endpoints connect remote clients to selected application services.
- The request-and-response round trip is the defining communication pattern of consuming a web service.
- Local APIs and web services can describe similar interactions, but they differ in delivery mechanism and scope of access.
- Exposing services allows mobile apps, dashboards, partners, and other systems to use shared application functionality.