APIs and Web Services: How Programs Communicate

When a weather app on a phone displays the current temperature, it almost certainly did not generate that data itself. It sent a request to a remote server, received a structured response, and rendered the result on screen — all in under a second. That exchange is an API call, and it is happening billions of times per day across virtually every connected application in existence. This page covers what APIs and web services are, how the request-response cycle actually works, where these patterns appear in practice, and how to think about choosing between different architectural approaches.

Definition and scope

An API — Application Programming Interface — is a defined contract between two pieces of software specifying how one can request something from the other. The W3C (World Wide Web Consortium), which coordinates web standards internationally, frames web services specifically as software systems designed to support interoperable machine-to-machine interaction over a network.

The scope is broader than it might first appear. APIs exist at multiple layers of computing: operating system APIs let applications talk to hardware, library APIs expose reusable functions within a codebase, and web APIs let distributed systems communicate across the internet. The term "web service" typically refers to that last category — APIs accessible over HTTP or HTTPS, often returning data in JSON or XML format.

This sits naturally within the broader landscape of programming concepts, alongside topics like functions and methods and object-oriented design. Grasping APIs unlocks the ability to build software that does not have to solve every problem itself.

How it works

The fundamental pattern is request and response. A client — which might be a browser, a mobile app, or another server — sends a structured request to an endpoint, a specific URL that represents a resource or action. The server processes the request and returns a response, typically with a status code and a payload.

The most common architecture for modern web APIs is REST (Representational State Transfer), described by Roy Fielding in his doctoral dissertation at UC Irvine in 2000. RESTful APIs map operations to standard HTTP methods:

  1. GET — retrieve a resource without modifying it
  2. POST — submit data to create a new resource
  3. PUT — replace an existing resource entirely
  4. PATCH — update part of an existing resource
  5. DELETE — remove a resource

A well-designed REST API uses URLs that represent nouns (/users/42) rather than verbs (/getUser?id=42), and returns appropriate HTTP status codes: 200 for success, 404 when a resource is not found, 401 when authentication fails, 500 when something breaks on the server side.

Authentication is almost always part of the equation. OAuth 2.0, documented by the IETF (Internet Engineering Task Force) in RFC 6749, is the dominant standard for delegated authorization — the mechanism behind "Sign in with Google" flows and third-party app permissions.

Rate limiting is another practical reality. The GitHub REST API, for example, allows unauthenticated requests at 60 per hour and authenticated requests at 5,000 per hour — a ratio that illustrates why proper authentication matters even when it is not strictly required.

Common scenarios

APIs appear wherever two systems need to exchange information. The patterns cluster around a few recognizable situations:

Data retrieval: A dashboard application pulls sales figures from a backend database through an internal API. The frontend never touches the database directly — the API enforces access rules and formats the response.

Third-party integration: An e-commerce site uses the Stripe API (documented publicly under Stripe's developer resources) to process payments, rather than building payment infrastructure from scratch.

Microservices communication: Larger applications often break into independently deployable services, each exposing an API. An order service, an inventory service, and a notification service each handle one domain and communicate via API calls. The OpenAPI Specification, maintained by the OpenAPI Initiative, provides a standard format for documenting these interfaces.

Webhooks (reverse APIs): Instead of polling an endpoint repeatedly, a system registers a URL and a remote service pushes data to it when events occur. A payment processor sending a confirmation when a charge completes is a classic webhook pattern.

Decision boundaries

Choosing between architectural approaches is one of the practical questions that shapes how a system gets built. The two most common contenders beyond REST are SOAP and GraphQL.

REST vs. SOAP: SOAP (Simple Object Access Protocol) is an older, XML-based messaging protocol with stricter standards and built-in error handling. The W3C publishes the SOAP 1.2 specification. It remains common in enterprise and financial systems where formal contracts between parties matter more than developer convenience. REST is lighter, easier to debug with standard tools, and dominates in public-facing APIs.

REST vs. GraphQL: GraphQL, developed internally at Meta and open-sourced in 2015, lets clients specify exactly which fields they need in a single query, rather than receiving a fixed payload structure. This reduces over-fetching (getting more data than needed) and under-fetching (needing multiple requests to assemble a complete picture). The tradeoff is added complexity in schema design and caching. The GraphQL Foundation, hosted under the Linux Foundation, maintains the specification.

The right choice depends on the specific use case: REST for standard, cacheable, resource-oriented APIs; SOAP when working within enterprise systems that require it; GraphQL when clients have genuinely varied data needs and over-fetching has become a real performance cost.

Understanding APIs also connects directly to web development practice and debugging strategies, since tracking down a failed API call — with its status codes, malformed payloads, and authentication headers — is one of the more instructive exercises in understanding how distributed software actually behaves. The full reference site at Programming Authority covers these adjacent topics in comparable depth.

References