An API (Application Programming Interface) is a defined set of rules and protocols that allows one software program to communicate with another, specifying what requests can be made, how they must be formatted, and what responses to expect. APIs are the invisible connective tissue of modern software -- the reason your weather app knows tomorrow's forecast, your payment goes through when you tap your phone at checkout, and you can sign into dozens of websites with a single Google account. Whether you are a software developer building integrations, a product manager evaluating technical capabilities, or a business leader making technology decisions, understanding how APIs work is foundational knowledge for navigating the digital economy.

What Is an API? The Core Concept

The Interface Analogy

The word interface is the key to understanding APIs. An interface is a defined boundary through which two systems interact, with agreed-upon rules governing how each side behaves.

Consider a power outlet. It has a standardized interface: a specific shape, voltage (120V in the United States, 230V in most of Europe), and connection protocol. Any device built to that standard can plug in and draw electricity. The outlet does not need to know whether the device is a lamp, a refrigerator, or a computer. The device does not need to know whether the electricity comes from a coal plant, a wind farm, or a nuclear reactor. The interface abstracts away the complexity on both sides, allowing the two systems to interact through a simple, predictable contract.

An API does the same thing for software. It defines:

  • What requests can be made -- what operations are available to the requesting system
  • How requests must be formatted -- what data must be included and in what structure
  • What responses look like -- what the requesting system will receive back
  • What error codes mean -- what happened when something goes wrong

The system offering the API is called the provider (or server). The system making requests is the consumer (or client). Neither needs to understand the other's internal workings. Both only need to understand the interface -- the contract between them.

"Any sufficiently advanced technology is indistinguishable from magic." -- Arthur C. Clarke. APIs are the mechanism by which that "magic" is delivered: they hide enormous complexity behind simple, predictable interfaces.

A Brief History

The term "Application Programming Interface" dates to a 1968 paper by E.F. Codd and colleagues, though the concept existed earlier in the form of subroutine libraries. Early APIs were primarily local -- one program calling functions in another program on the same computer.

The transformative shift came with networked APIs in the late 1990s and early 2000s. As the internet matured, companies began exposing their services over HTTP, allowing remote systems to interact with them. Salesforce launched one of the first major web APIs in 2000. Amazon Web Services followed in 2002. eBay, Google Maps, and Flickr released public APIs in 2004-2005, sparking the mashup era in which developers combined data from multiple APIs to create entirely new products.

By 2023, Postman's State of the API Report found that 89% of developers consider APIs more important to their organizations than they were the previous year. RapidAPI reported over 40,000 public APIs available in its marketplace. APIs have evolved from a technical implementation detail into a fundamental business strategy.

How a REST API Works

The Dominant Architecture

REST (Representational State Transfer) is the dominant architectural style for web APIs. It was formalized by computer scientist Roy Fielding in his 2000 doctoral dissertation at the University of California, Irvine. REST became the default approach for most public APIs because of its simplicity and natural alignment with the existing structure of the web -- HTTP protocols, URLs, and standard data formats.

A REST API exposes resources -- data entities like users, products, orders, or messages -- through URLs (also called endpoints). Each resource has a distinct URL, and you interact with it using standard HTTP methods:

HTTP Method Purpose Example Analogy
GET Retrieve a resource GET /users/123 Looking up a contact in a phonebook
POST Create a new resource POST /orders Placing a new order at a restaurant
PUT Replace a resource entirely PUT /users/123 Rewriting an entire contact card
PATCH Update part of a resource PATCH /users/123 Changing just the phone number on a card
DELETE Remove a resource DELETE /orders/456 Canceling a restaurant order

When a client makes a request, it includes any needed data (typically as JSON in the request body) and authentication credentials (typically in the request headers). The server processes the request and returns a response with two critical pieces: an HTTP status code indicating success or failure, and data in the response body.

HTTP Status Codes: The Language of API Responses

Status codes follow a logical numbering system that any developer learns to read intuitively:

  • 2xx -- Success: The request was received, understood, and processed.

    • 200 OK -- Standard success response
    • 201 Created -- A new resource was successfully created
    • 204 No Content -- Success, but nothing to return (common for DELETE)

  • 4xx -- Client Error: Something was wrong with the request.

    • 400 Bad Request -- Malformed request (missing required fields, wrong data types)
    • 401 Unauthorized -- Missing or invalid authentication credentials
    • 403 Forbidden -- Authenticated but not permitted to perform this action
    • 404 Not Found -- The requested resource does not exist
    • 429 Too Many Requests -- Rate limit exceeded

  • 5xx -- Server Error: The request was valid, but the server failed to process it.

    • 500 Internal Server Error -- Something went wrong on the server side
    • 502 Bad Gateway -- The server received an invalid response from an upstream service
    • 503 Service Unavailable -- The server is temporarily overloaded or under maintenance

A well-designed REST API is predictable. Anyone who understands HTTP and the URL structure can reason about what is available and how to interact with it. This predictability is why REST became the universal language of web services and why it remains the default choice for most public APIs more than two decades after Fielding's dissertation.

REST vs. GraphQL vs. gRPC: Choosing the Right Architecture

REST is not the only approach to building APIs, and understanding the alternatives clarifies the tradeoffs that engineers and product teams navigate when designing systems.

GraphQL: The Client-Controlled Query

GraphQL is a query language for APIs developed at Facebook (now Meta) by Lee Byron, Nick Schrock, and Dan Schafer in 2012, open-sourced in 2015. Instead of multiple fixed endpoints, GraphQL exposes a single endpoint. Clients send queries that specify exactly what data they need, and the server returns exactly that -- no more, no less.

The REST problem GraphQL solves: Consider a mobile app displaying a user profile. With REST, the app might need three separate requests: one for the user's basic information (/users/123), one for their recent posts (/users/123/posts), and one for their follower count (/users/123/followers). Each response might return far more fields than the app actually needs. This creates two well-known problems:

  • Over-fetching: Receiving more data per request than the client needs, wasting bandwidth and processing time
  • Under-fetching: Needing multiple requests to assemble the data for a single screen, increasing latency

GraphQL solves both by letting the client specify, in a single query, exactly which fields from which related resources it needs. The server returns precisely that data structure and nothing else.

The tradeoffs: GraphQL is more complex to implement and operate than REST. HTTP caching, which works naturally with REST's URL-per-resource model, becomes significantly harder with GraphQL because every query to the single endpoint can request different data. Server-side performance optimization is more challenging because the server cannot predict what data combinations clients will request. For simple APIs with stable, well-understood data requirements, REST is typically easier and more performant. GraphQL shines for complex, data-rich products with many different clients -- web, mobile, third-party integrations -- that each have different data needs.

gRPC: The High-Performance Internal Protocol

gRPC is a high-performance Remote Procedure Call framework developed by Google and open-sourced in 2015. Instead of HTTP/JSON, gRPC uses Protocol Buffers (a compact binary serialization format developed by Google) and HTTP/2. This combination makes gRPC substantially faster and more bandwidth-efficient than REST for high-volume, low-latency service-to-service communication.

Where REST sends human-readable JSON text, gRPC sends compact binary data. Where REST requires a new connection for each request-response cycle (in HTTP/1.1), gRPC supports multiplexed streaming over persistent connections (via HTTP/2). The performance difference is substantial: benchmarks typically show gRPC handling 5-10x more requests per second than equivalent REST APIs, with significantly lower latency.

gRPC is the standard for internal microservice communication at companies like Google, Netflix, Square, and Lyft. It is less suitable for public-facing APIs because browsers cannot call gRPC natively (requiring a proxy layer) and because clients need the Protocol Buffer definition files that describe the API contract -- a barrier for external developers.

Feature REST GraphQL gRPC
Data format JSON (human-readable) JSON (human-readable) Protocol Buffers (binary)
Multiple resources per request No (requires multiple calls) Yes (single query) Yes (streaming)
HTTP caching Excellent (native) Complex (single endpoint) Minimal
Browser support Full Full Requires proxy
Typical use case Public APIs, CRUD services Complex frontends, mobile apps Internal microservices
Learning curve Low Medium High
Performance Good Good Excellent

API Authentication and Security

APIs are not typically open to the entire internet. They require authentication (proof of who you are) and often authorization (confirmation that you are permitted to do what you are requesting).

API Keys

The simplest and most common form of API authentication. An API key is a unique string, typically 32-64 characters, that the provider generates for you when you register for access. You include it in every request, usually as an HTTP header:

Authorization: Bearer sk_live_abc123xyz789...

The server looks up the key, identifies your account, checks the permissions associated with it, and decides whether to fulfill the request. API keys serve multiple purposes beyond authentication: they allow providers to track usage by customer, enforce rate limits (how many requests per second or per month you are allowed), and bill based on consumption.

The critical security rule: API keys are secrets, equivalent in sensitivity to passwords. They should never be committed to version control (a 2019 study by North Carolina State University found over 100,000 repositories on GitHub containing exposed API keys). They should never be included in client-side browser code where users can inspect them via developer tools. They should be stored in environment variables or secret management systems, and rotated immediately when compromised.

OAuth 2.0: Delegated Authorization

For scenarios where a user needs to authorize an application to access their data on a third-party service, API keys are insufficient. OAuth 2.0, formalized in RFC 6749 (2012), is the standard protocol for delegated authorization -- the mechanism behind "Sign in with Google," "Connect to Spotify," and "Authorize with GitHub."

The OAuth flow works through a carefully choreographed sequence:

  1. Your application redirects the user to the authorization server (e.g., Google's login page)
  2. The user logs in and approves the specific permissions your application is requesting (e.g., "read your email," "access your calendar")
  3. The authorization server redirects back to your application with a short-lived authorization code
  4. Your application exchanges that code -- server-to-server, using your application's secret credentials -- for an access token
  5. Your application uses the access token to make API calls on behalf of that user

The critical security property: the user's actual password is never seen by your application. The authorization server (Google, GitHub, etc.) vouches for the user's identity, and your application receives only the specific permissions the user explicitly approved. This is why OAuth became the universal standard for third-party integrations -- it enables powerful interoperability without requiring users to share their credentials with every application they use.

JWT (JSON Web Tokens)

JWTs are a common mechanism for carrying authentication and authorization information in API requests. A JWT is a digitally signed token containing claims about the user (their identity, roles, permissions, and the token's expiration time). The server can verify the token's authenticity without making a database lookup for every request, which makes JWTs efficient for high-volume APIs.

A typical JWT flow: the user authenticates once (via username/password, OAuth, or another mechanism), receives a JWT, and includes it in the header of subsequent API requests. The server verifies the digital signature, extracts the claims, and processes the request accordingly.

Webhooks vs. Polling: Two Models for Real-Time Data

One of the most practically important architectural decisions in API design is the choice between polling and webhooks for receiving updates.

Polling: The Ask-Repeatedly Model

Polling means your application sends repeated requests to a server asking for updates: "Any new orders?" "Has the payment been confirmed?" "Are there new messages?" You might poll every 5 seconds, every 30 seconds, or every 5 minutes, depending on the time-sensitivity of the updates.

Polling is simple to implement -- it uses standard API calls on a schedule. But it is fundamentally wasteful: the vast majority of poll requests return nothing new. At scale, thousands of clients polling creates enormous unnecessary server load. A 2019 analysis by Zapier estimated that the average polling-based integration wastes 98.5% of its API calls on empty responses.

Webhooks: The Event-Driven Model

Webhooks invert the polling model entirely. Instead of repeatedly asking "anything new?", you register a URL -- your webhook endpoint -- and tell the server what events you care about. When those events occur, the server sends an HTTP POST request to your URL immediately with the relevant data.

Real-world examples make this concrete:

  • Stripe: When a payment is completed, Stripe sends a webhook to your server with the payment details, so your system can fulfill the order.
  • GitHub: When a pull request is merged, GitHub sends a webhook to your CI/CD system, triggering an automatic deployment.
  • Shopify: When a new order is placed, Shopify sends a webhook to your inventory management system to update stock levels.
  • Twilio: When an SMS reply is received, Twilio sends a webhook to your application with the message content.

Webhooks are event-driven and efficient -- communication happens precisely when something happens, not on a wasteful polling schedule. The main complications are security (your endpoint must be publicly accessible, requiring signature verification to prevent spoofing) and idempotency (your endpoint must handle the possibility that the same event is delivered more than once, because webhook delivery systems typically retry on failure).

Real-World API Examples That Power the Digital Economy

Stripe: The Payment Infrastructure

Stripe, founded by Irish brothers Patrick and John Collison in 2010, built a company valued at over $50 billion by making one thing excellent: payment processing via a clean, developer-friendly API. When a customer enters their card on an e-commerce site, the site never touches the card details directly. The browser sends the card information to Stripe's API (via Stripe.js), which handles tokenization (converting the card number into a single-use token), communicates with the card network (Visa, Mastercard, etc.), and returns a success or failure response. The merchant's server never sees the raw card number, dramatically simplifying PCI compliance.

Stripe processes hundreds of billions of dollars annually. Its API documentation is widely considered the gold standard in the industry -- clear, comprehensive, with working code examples in multiple languages.

Google Maps Platform: Location Intelligence

When you open a restaurant delivery app and see a map with your driver's location, that map is not built by the delivery company. It is Google Maps rendered through the Maps JavaScript API, with the company's custom markers, routing data, and real-time location updates layered on top. Google charges per API call beyond a free tier -- approximately $7 per 1,000 map loads and $5 per 1,000 geocoding requests as of 2024.

An estimated 5 million websites and applications use the Google Maps API, according to BuiltWith. The platform handles over 1 billion API requests per day.

Twilio: Communications as a Service

Twilio, founded by Jeff Lawson in 2008, provides communications infrastructure via API. When you receive a text message saying "Your order has shipped" or "Your verification code is 482931," that message was almost certainly sent through Twilio's Messaging API (or a competitor like Vonage or MessageBird). The sending company's system makes an API call with the recipient's phone number and message text; Twilio routes it to the appropriate mobile carrier.

Twilio handles over 100 billion API interactions annually and powers communications for companies including Uber, Airbnb, Netflix, and Twitch.

OpenAI API: AI as a Service

The OpenAI API represents a newer category: artificial intelligence capabilities delivered as an API service. Applications built on GPT models do not contain the AI model themselves -- the models are far too large (hundreds of gigabytes) to run on most hardware. Instead, they send prompts to OpenAI's API and receive generated text back. Every ChatGPT-powered tool, AI writing assistant, customer service chatbot, and coding helper using GPT models is a client of this API, paying per token for generation.

The OpenAI API processed an estimated 100 billion tokens per day by mid-2024, illustrating the scale at which AI applications rely on API infrastructure.

API Design Principles Worth Knowing

Whether you are building APIs or evaluating them, several principles separate well-designed APIs from frustrating ones:

Consistency is the most important quality. An API that uses user_id in one endpoint and userId in another, or returns dates as Unix timestamps in some responses and ISO 8601 strings in others, creates traps for every developer who integrates with it. Daniel Jacobson, former VP of Engineering at Netflix, has written extensively about how API consistency reduces integration time and support burden. Stripe's API is consistent to an almost obsessive degree, which is a primary reason developers prefer it.

Versioning protects existing consumers when the API evolves. Common approaches include URL versioning (/v1/users, /v2/users) and header versioning (Accept: application/vnd.api+json;version=2). Without versioning, any change to the API's behavior or data structure risks breaking existing clients -- a cardinal sin in API design.

Idempotency means that making the same request multiple times has the same effect as making it once. This is critical for operations involving money or state changes, where network failures might create ambiguity about whether a request was processed. Stripe requires clients to send a unique Idempotency-Key with payment requests so that retried requests are not processed twice -- preventing the nightmare scenario of charging a customer multiple times for one purchase.

Rate limiting protects the provider from abuse and runaway clients. Well-designed rate limiting includes informative response headers that tell clients how many requests they have remaining and when the limit resets, rather than simply returning a 429 Too Many Requests error with no guidance.

Clear, actionable error messages dramatically reduce developer frustration and support load. An error that says "Invalid request" helps nobody. An error that says "The email field is required and must be a valid email address. You provided: null" tells the developer exactly what to fix.

The API Economy: Why APIs Matter Beyond Software

APIs have transformed not just software architecture but entire business models. The concept of the API economy describes how organizations expose their core competencies as services that others can build on, generating revenue from each interaction.

Stripe built a company worth tens of billions of dollars by making one thing -- payment processing -- excellent and exposing it via a clean API. Twilio did the same for communications. SendGrid (now part of Twilio) for email delivery. Mapbox for maps and geolocation. Algolia for search. Each of these companies enables startups to build products in days that would have taken months or years to build from scratch, by purchasing commodity infrastructure as a service and focusing engineering effort on their specific differentiator.

Salesforce generates approximately 50% of its total transactions through its API, according to the company's developer documentation. Expedia generates over 90% of its revenue through API-based partner integrations. eBay processes more than 8 billion API calls per day.

For non-engineers, understanding APIs matters because:

  • Product decisions depend on what APIs exist, what they cost, and what constraints their terms of service impose
  • Security decisions rest on understanding authentication, key management, and data handling practices
  • Partnership decisions frequently involve evaluating and negotiating API integrations
  • Competitive strategy increasingly involves API ecosystems -- who can integrate with whom, and on what terms

An API is ultimately an agreement -- a contract about how two parties will exchange value. Understanding that contract, even at a conceptual level, is increasingly a prerequisite for effective work in any organization that runs on software.

Getting Started: How to Make Your First API Call

For those who want to move from theory to practice, here is the simplest path to making a real API call:

  1. Choose a free, public API: OpenWeatherMap (weather data), JSONPlaceholder (fake data for testing), or the Pokemon API (yes, it exists) all offer free access without requiring authentication.

  2. Use a tool: Postman (desktop application) or curl (command line) are the standard tools for making API requests without writing code. Postman provides a graphical interface; curl is text-based but universally available.

  3. Make a GET request: Point Postman at https://jsonplaceholder.typicode.com/users/1 and click Send. You will receive a JSON response containing a fake user's data. That is an API call -- you requested a resource, and the server returned it.

  4. Read the documentation: Every well-designed API provides documentation describing its endpoints, required parameters, authentication method, and response formats. Stripe's documentation (https://stripe.com/docs/api) is widely considered the best in the industry and worth reading as a model even if you never use Stripe.

The gap between understanding APIs conceptually and using them practically is smaller than most people think. One afternoon with Postman and a public API is enough to make the abstract concrete.

References and Further Reading

Tags

API REST API software development web development programming

Frequently Asked Questions

What is an API in simple terms?

An API (Application Programming Interface) is a defined way for two software programs to communicate with each other. One program sends a structured request, and the other sends back a structured response. APIs are the reason you can log into a website using Google, see a map inside an app, or pay for something online without the retailer ever handling your card details.

What is the difference between REST and GraphQL?

REST APIs use a set of standard URL endpoints — each representing a resource — and fixed data structures are returned for each endpoint. GraphQL is a query language that lets clients specify exactly what data they need in a single request, reducing over-fetching and under-fetching. REST is simpler to build and cache; GraphQL is more flexible for complex, data-heavy frontends with many different data requirements.

What is an API key and why is it needed?

An API key is a unique identifier — typically a long string of characters — that tells the API server who is making a request. It serves two purposes: authentication (proving you are a legitimate user) and authorization (controlling what you are allowed to access). API keys also allow providers to track usage, enforce rate limits, and bill for consumption.

What is the difference between a webhook and polling?

Polling means your application repeatedly asks a server 'do you have any updates?' at regular intervals, whether or not anything has changed — this wastes resources. A webhook reverses the model: you give the server your URL, and it sends you a notification the moment something happens. Webhooks are event-driven and efficient; polling is simple but wasteful at scale.

What are some everyday examples of APIs in use?

When you use a food delivery app and see a live map of your driver, that map is from Google Maps API. When you complete a checkout and your card is charged, that transaction runs through Stripe's or Braintree's payment API. When a website lets you sign in with Apple or Google, OAuth APIs handle that handshake. When you receive an order confirmation SMS, that message was sent via Twilio's messaging API.

Share this article