What Is an API? How APIs Work Explained Simply

Picture this: a flight booking app on your phone simultaneously checks availability from Delta, United, and Emirates, processes your credit card through Stripe, sends your confirmation via Twilio SMS, and pins your departure gate on Google Maps — all within a few seconds of pressing "Book." Every single one of those actions is an API call. You never saw the implementation details of any airline's reservation system, Stripe's payment vault, or Google's mapping database. You just called an interface and got a result.

That is the core idea behind an API: a defined contract between two pieces of software. The consumer (your app) does not need to know how the provider (Stripe, Google, Delta) works internally. It only needs to know what inputs to send and what outputs to expect.

According to Nordic APIs, approximately 83% of all internet traffic is API traffic. Postman's 2025 State of the API Report — surveying 5,700+ developers across 100+ countries — found that 83.2% of development teams have adopted an API-first approach. APIs are not a feature; they are the architecture of the modern web.

The Anatomy of an API Call

Every API interaction involves the same four components regardless of protocol: a request from the client, a URL endpoint identifying the resource, optional headers for metadata and authentication, and a response containing the result.

// A real Stripe API call: charge a card
const response = await fetch('https://api.stripe.com/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',   // API key authentication
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    amount: '2000',       // $20.00 in cents
    currency: 'usd',
    source: 'tok_visa',   // tokenized card
    description: 'Order #1234',
  }),
});

const charge = await response.json();
// charge.id = "ch_3MqLiJLkdIwHu7ix0PLkR9Ei"
// charge.status = "succeeded"
// charge.amount = 2000

Stripe's API processes over 500 million API requests daily from 4.5 million+ active websites. The call above abstracts away PCI compliance, card network communication, fraud scoring, bank authorization, and transaction logging. You send a request; you get a result.

Request Structure: The Four Key Parts

The response mirrors this structure: a status code (200 OK, 404 Not Found, 429 Too Many Requests), response headers, and a body — almost always JSON in modern APIs. Use BytePane's JSON Formatter to inspect and pretty-print API responses during development.

A Brief History: From SOAP to REST to GraphQL

APIs are not new. The concept predates the web. But the current era of web APIs began in the early 2000s with two competing approaches.

SOAP (Simple Object Access Protocol), introduced by Microsoft in 1998, wrapped all operations in verbose XML envelopes and required a WSDL descriptor file to define the interface. It worked, but it was tedious — writing a SOAP client often meant generating hundreds of lines of boilerplate.

In 2000, Roy Fielding published his PhD dissertation at UC Irvine: "Architectural Styles and the Design of Network-based Software Architectures." Chapter 5 described REST (Representational State Transfer) — an architectural style that used HTTP methods (GET, POST, PUT, DELETE) and URLs as identifiers for resources. Fielding had co-authored the HTTP 1.0 spec in 1994 and was the primary author of HTTP 1.1. He was describing how the web already worked and formalizing it as a design philosophy.

REST won. By 2010, nearly every major consumer API — Twitter, Facebook, GitHub, Stripe — was RESTful. By 2015, JSON had replaced XML as the dominant response format. According to the Postman 2024 State of the API Report (surveying 5,600+ developers), REST is used by 83–93.4% of API developers today.

In 2015, Facebook open-sourced GraphQL, a query language for APIs born from the frustration of maintaining multiple REST endpoints for their mobile apps. GraphQL flips the model: instead of multiple endpoints each returning fixed data, a single endpoint accepts queries where the client specifies exactly what fields it needs.

# REST: 3 round trips to load a user profile page
GET /api/users/42           → full user object (2 KB)
GET /api/users/42/posts     → array of posts (8 KB)
GET /api/users/42/followers → follower count + list (4 KB)

# GraphQL: 1 request, exactly the fields needed (400 bytes)
query {
  user(id: "42") {
    name
    avatarUrl
    postCount
    followerCount
  }
}

GraphQL adoption has grown significantly: per Postman's 2024 report, 22.5% of developers use GraphQL, and adoption among Fortune 500 companies surged 340% from 2021 to 2024. For a detailed comparison, see our guide on GraphQL vs REST API.

API Protocols: REST, GraphQL, gRPC, and WebSockets

Choosing a protocol is not a religious decision — it is an engineering trade-off based on your data model, client diversity, and performance requirements.

REST (Representational State Transfer)

REST maps HTTP verbs to CRUD operations against URL-identified resources. It is stateless (no session memory on the server), cacheable (GET requests work with HTTP caching out of the box), and works with every HTTP client ever built. REST is the right default for most APIs.

GraphQL

One endpoint, typed schema, client-driven queries. Eliminates over-fetching and under-fetching. Best for complex data graphs with multiple client types (mobile, web, IoT) that need different data shapes. Adopted by GitHub, Shopify, Twitter, and most large product companies for their internal APIs.

gRPC (Google Remote Procedure Call)

Built on HTTP/2 and Protocol Buffers (binary serialization). Roughly 7–10x faster than REST+JSON for the same payload because Protobuf messages are significantly smaller and faster to parse than JSON. The trade-off: no browser support without a proxy layer (grpc-web), and Protobuf schemas add build complexity. Used by Netflix, Uber, and Google for internal microservice communication where throughput matters more than browser compatibility.

// gRPC service definition (.proto file)
syntax = "proto3";

service UserService {
  rpc GetUser (UserRequest) returns (UserResponse);
  rpc ListUsers (ListUsersRequest) returns (stream UserResponse);
}

message UserRequest {
  string id = 1;
}

message UserResponse {
  string id = 1;
  string name = 2;
  string email = 3;
}

// Benchmark comparison for 1,000 requests (user profile payload):
// REST + JSON:      ~450ms avg,  ~2.1 KB per response
// gRPC + Protobuf: ~60ms avg,   ~180 bytes per response

WebSockets

WebSockets open a persistent, bidirectional connection between client and server. Unlike HTTP (request → response → connection closed), WebSockets stay open. The server can push data to the client at any time without the client polling. Essential for real-time use cases: trading dashboards, collaborative editors (like Figma), live chat, and multiplayer games. For a complete implementation guide, see our WebSockets tutorial.

How API Authentication Works

Every production API gates access with authentication. The four main mechanisms are API keys, OAuth 2.0, JWT tokens, and mutual TLS (mTLS).

// 1. API Key — simplest, identifies the app (not the user)
GET /v1/forecast
Authorization: Bearer api_key_abc123xyz

// 2. OAuth 2.0 — delegates user permissions without sharing passwords
// Step 1: Redirect user to provider
GET https://github.com/login/oauth/authorize?client_id=abc&scope=repo

// Step 2: Exchange callback code for access token
POST https://github.com/login/oauth/access_token
{ code: "returned_code", client_secret: "..." }

// Step 3: Use token
GET https://api.github.com/user
Authorization: Bearer gho_16C7e42F292c6912E7710c838347Ae178B4a

// 3. JWT — self-contained token, no server-side session lookup needed
// Header.Payload.Signature — all verifiable with public key
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI0MiJ9.abc...

// 4. mTLS — both sides present certificates (used in financial/healthcare)
// Client cert proves client identity; server cert proves server identity

For a deep dive into each method with security trade-offs, see our guide on API authentication methods. To inspect the contents of a JWT token during development, use BytePane's JWT Decoder — it decodes the header and payload in your browser without sending tokens to any server.

The Economics of APIs: Why They Are a Business Strategy

APIs are not just technical plumbing. They are revenue channels. The numbers are striking:

• 90%

  Expedia's API revenue share

  Nine out of ten dollars Expedia earns flows through partner APIs — travel agents, booking engines, and comparison sites that consume their inventory via API and pay commissions per booking.

• 60%

  eBay's revenue from APIs

  eBay's public API ecosystem lets third-party sellers, price aggregators, and shipping tools integrate directly, generating the majority of eBay's transaction volume.

• 50%

  Salesforce's API revenue share

  Half of Salesforce's revenue comes from API integrations — CRM connectors, marketing automation platforms, and custom enterprise integrations built on their REST and SOAP APIs.

The Postman 2025 State of the API Report found that 65% of revenue-generating API organizations now treat APIs as products, with dedicated teams, versioning, monetization strategies, and developer portals. The API management market is growing from $10 billion in 2025 to a projected $108.61 billion by 2033, per Precedence Research — a 34.7% compound annual growth rate.

Real-World API Examples Every Developer Should Know

Abstract concepts click faster with concrete examples. Here are four APIs that collectively power a significant portion of the applications you use daily.

Stripe: Payments API

Stripe's REST API processes 500M+ daily requests across 4.5M+ active websites. Its genius is abstraction: you never touch raw card numbers. Instead, you tokenize the card in the browser via Stripe.js (meaning PAN data never hits your server), then pass the token to Stripe's API to charge it. The API handles PCI-DSS compliance, fraud detection, currency conversion, and dispute management.

Twilio: Communications API

Twilio exposes telecom infrastructure as a web API. Instead of negotiating with carrier networks, buying SIM card pools, and building SMS routing infrastructure, you POST to https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages with a phone number and body text. Twilio handles carrier negotiation, delivery receipts, and number provisioning for 250,000+ businesses and 10 million+ developers.

Google Maps Platform

Google Maps APIs are integrated into 5 million+ active apps weekly, reaching 2.2 billion monthly active users through those apps. The suite includes: Geocoding API (address → coordinates), Directions API (routing), Places API (business data), and Maps JavaScript API (embeddable maps). Each call returns structured JSON — for instance, a coordinates lookup for "1600 Amphitheatre Parkway" returns lat/lng within milliseconds from Google's distributed infrastructure.

OpenAI API

The API that accelerated AI adoption in production applications. One POST request to /v1/chat/completions runs GPT-4 on your prompt without managing a single GPU. Per the Postman 2024 report, OpenAI accounts for 78.5% of all AI-related API traffic on Postman's platform. The AI API market is projected to grow from $48.5 billion in 2024 to $246.87 billion by 2030 (Grand View Research).

API Rate Limiting, Versioning, and Status Codes

Three operational realities every API consumer needs to handle:

Rate Limiting

APIs cap requests per time window. GitHub allows 5,000 requests/hour for authenticated users. Exceed this and you get HTTP 429. The response headers tell you what you have left:

// Response headers from GitHub API
X-RateLimit-Limit: 5000          // max per hour
X-RateLimit-Remaining: 4921      // left in current window
X-RateLimit-Reset: 1677649638    // Unix timestamp when window resets
X-RateLimit-Used: 79             // used so far

// Implement exponential backoff when you hit 429
async function callWithBackoff(fn, maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status !== 429 || i === maxRetries - 1) throw err;
      await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
    }
  }
}

Versioning

APIs change. Version your API to avoid breaking existing consumers. The three common strategies are URL versioning (/v1/users), header versioning (Accept: application/vnd.api.v2+json), and query parameter versioning (/users?version=2). URL versioning is the most widely used because it is explicit and easy to test in a browser. For best practices, see our REST API best practices guide.

HTTP Status Codes

APIs communicate success and failure through status codes defined in RFC 9110. The ones you will encounter most: 200 OK (success), 201 Created (resource created), 400 Bad Request (your payload is malformed), 401 Unauthorized (missing auth), 403 Forbidden (authenticated but lacking permission), 404 Not Found, 429 Too Many Requests, and 500 Internal Server Error. Our HTTP status codes reference covers all 60+ codes with usage guidelines.

Webhooks: Push vs Pull

Traditional API calls are pull: your application asks a server "did anything change?" at regular intervals (polling). Webhooks are push: the server notifies your application the moment an event occurs.

// Polling: inefficient, high latency, wastes API quota
setInterval(async () => {
  const status = await stripe.charges.retrieve(chargeId);
  if (status.paid) handlePayment(status); // check every 5 seconds
}, 5000);

// Webhook: Stripe POSTs to your URL when the event happens
// Express.js webhook handler
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];

  // Always verify webhook signatures to prevent forgery
  const event = stripe.webhooks.constructEvent(req.body, sig, process.env.WEBHOOK_SECRET);

  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object;
    fulfillOrder(paymentIntent.metadata.orderId);
  }

  res.json({ received: true });
});

Always verify webhook signatures. Without signature verification, any HTTP client can POST to your webhook endpoint and trigger business logic with forged data. Every major provider (Stripe, GitHub, Twilio) includes a signature in the request headers that you verify against a shared secret.

API Documentation: The Make-or-Break Factor

Bad documentation is the top reason developers abandon an API. Postman's 2025 report found that 55% of API teams cite inconsistent documentation as their primary collaboration blocker.

The industry standard for REST API documentation is the OpenAPI Specification (formerly Swagger), maintained by the Linux Foundation. An OpenAPI YAML or JSON file describes every endpoint, parameter, response schema, and authentication method in a machine-readable format. Tools like Swagger UI and Redoc render it into interactive documentation. Here is a minimal example:

# openapi.yaml
openapi: "3.1.0"
info:
  title: User API
  version: "1.0.0"
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "404":
          description: User not found

Frequently Asked Questions

Related Articles