When you open a weather app on your phone, you are not looking at weather data that lives inside your phone. The app sends a request to a remote server, that server consults meteorological databases and satellite feeds, and it sends back the current temperature and forecast — typically in under a second. The translation layer that makes this exchange possible is called an API.
When you tap "Pay with Apple Pay" at a checkout, your device does not have access to your bank. An API call travels from the retailer's payment terminal to a payment processor, which routes it to your bank, which authorizes the transaction and routes a response back — the entire exchange happening faster than you finish tapping.
When you sign in to a new website using your Google account, Google's OAuth API is handling the authentication — verifying that you are who you say you are without ever giving the website your password.
APIs are the invisible connective tissue of modern software. Understanding what they are and how they work is not just relevant for software developers — it is increasingly relevant for anyone who builds products, makes technology decisions, or tries to understand how the digital world actually operates.
What Is an API?
API stands for Application Programming Interface. The word "interface" is the key — an interface is a defined boundary through which two systems interact, with agreed-upon rules about how each side behaves.
Think of a power outlet. It has a defined interface: a specific shape, voltage, and connection standard. Any device built to that standard can plug in and use the electricity — the outlet does not need to know what the device is, and the device does not need to know how the power plant generates electricity. The interface abstracts away the complexity on both sides.
An API does the same thing for software. It defines:
- What requests can be made — what operations are available
- How requests must be formatted — what information must be included and in what structure
- What responses look like — what the requesting system can expect to receive back
- What error codes mean — what happened if the request failed
The system offering the API (the server, the service, the database) is called the provider. The system making requests is the client or consumer. The provider does not need to expose its internal workings; the consumer does not need to understand how results are produced. Both only need to know the interface.
How a REST API Works
REST (Representational State Transfer) is the dominant architectural style for web APIs. REST was formalized in Roy Fielding's 2000 doctoral dissertation and has become the default approach for most public APIs because of its simplicity and alignment with the existing structure of the web (HTTP).
A REST API exposes resources — data entities like users, products, orders, or messages — through URLs. Each resource has a distinct URL, and you interact with it using standard HTTP methods:
| HTTP Method | Action | Example |
|---|---|---|
| GET | Retrieve a resource | GET /users/123 — fetch user with ID 123 |
| POST | Create a new resource | POST /orders — create a new order |
| PUT | Replace a resource completely | PUT /users/123 — update entire user record |
| PATCH | Update part of a resource | PATCH /users/123 — update just the email field |
| DELETE | Remove a resource | DELETE /orders/456 — cancel order 456 |
When a client makes a request, it includes any needed data (often as JSON in the request body) and authentication credentials (typically in the request headers). The server processes the request and returns a response with an HTTP status code indicating success or failure, and data in the response body.
Common status codes:
- 200 OK — the request succeeded
- 201 Created — a new resource was created
- 400 Bad Request — the request was malformed
- 401 Unauthorized — missing or invalid authentication
- 403 Forbidden — authenticated but not permitted
- 404 Not Found — the resource does not exist
- 500 Internal Server Error — something went wrong on the server
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.
REST vs GraphQL vs gRPC
REST is not the only approach, and understanding the alternatives helps clarify the tradeoffs.
GraphQL
GraphQL is a query language for APIs, developed by Facebook (now Meta) and 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: In REST, a mobile app displaying a user profile might need to make three separate requests: one for the user's basic info, one for their recent posts, and one for their follower count. Each request might return far more fields than the app needs. This is called over-fetching (too much data per request) and under-fetching (needing multiple requests for a single screen). GraphQL lets the client specify exactly which fields from which related resources it needs in a single request.
The trade-offs: GraphQL is more complex to implement than REST. Caching becomes harder (HTTP caching works naturally with REST's URL-per-resource model). For simple APIs with clear, stable data requirements, REST is typically easier. GraphQL shines for complex, data-rich products with many different clients (web, mobile, third-party) that each have different data needs.
gRPC
gRPC is a high-performance RPC (Remote Procedure Call) framework developed by Google. Instead of HTTP/JSON, it uses Protocol Buffers (a compact binary serialization format) and HTTP/2. This makes gRPC substantially faster and more efficient than REST for high-volume, low-latency internal service-to-service communication.
gRPC is common inside large distributed systems — the internal communication between microservices at Google, Netflix, or similar scale companies. It is less suitable for public-facing APIs because browsers cannot call gRPC natively, and it requires clients to have the proto file definitions that describe the API contract.
| Feature | REST | GraphQL | gRPC |
|---|---|---|---|
| Data format | JSON (usually) | JSON | Protocol Buffers (binary) |
| Multiple resources per request | No (requires multiple calls) | Yes (single query) | Yes (streaming) |
| Caching | Excellent (HTTP native) | Complex | Minimal |
| Browser support | Full | Full | Requires proxy |
| Typical use case | Public APIs, CRUD services | Complex frontends, mobile | Internal microservices |
| Learning curve | Low | Medium | High |
API Keys and Authentication
APIs are not typically open to the world. They require authentication — proof of who you are — and often authorization — confirmation that you are allowed to do what you are asking to do.
API Keys
The simplest form of API authentication. An API key is a unique string, typically 32-64 characters, that the API provider generates for you when you register. 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 what permissions are 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), and bill based on consumption.
The critical rule about API keys: they are secrets, equivalent to passwords. They should never be committed to version control, never included in client-side (browser) code where users can inspect them, and rotated when compromised.
OAuth 2.0
For scenarios where a user needs to authorize an application to access their data, API keys are not enough. OAuth 2.0 is the standard protocol for delegated authorization — the mechanism behind "Sign in with Google" and "Connect to Spotify."
The OAuth flow typically works like this:
- Your app redirects the user to Google's authorization page
- The user logs in to Google and approves the permissions your app is requesting
- Google redirects back to your app with a short-lived authorization code
- Your app exchanges that code (server-to-server, with your app's secret) for an access token
- Your app uses the access token to make API calls on behalf of that user
The user's actual Google password is never seen by your application. Google vouches for the user, and your application receives only the permissions the user specifically approved.
Webhooks vs Polling
One of the most practically important distinctions in API design is between polling and webhooks.
Polling
Polling means your application repeatedly asks a server for updates: "Are there any new orders?" "Any new messages?" "Has the payment been confirmed?" You might poll every 30 seconds, every minute, or every 5 seconds, depending on how time-sensitive the updates are.
Polling is simple to implement — you are just making regular API calls. But it is wasteful: most of the time, there is nothing new to report, and you are generating traffic and burning server resources on empty responses. At scale, thousands of clients polling creates enormous unnecessary load.
Webhooks
Webhooks reverse the model. Instead of asking repeatedly, you give the server a URL — your webhook endpoint — and tell it what events you care about. When those events occur, the server sends an HTTP POST request to your URL immediately.
When a payment is completed on Stripe, Stripe fires a webhook to your server: "Payment completed, here are the details." When someone fills out a Typeform, Typeform fires a webhook to your CRM with the response data. When a code review is approved in GitHub, GitHub fires a webhook to your CI/CD system to trigger a deployment.
Webhooks are event-driven and efficient — communication happens precisely when something happens, not on a polling schedule. The main complication is that your endpoint must be publicly accessible (which creates security considerations) and must handle the possibility that the same event is delivered more than once (idempotency).
Real-World API Examples
Understanding APIs abstractly is one thing; seeing how they underpin specific familiar products makes the concept concrete.
Stripe — The payment infrastructure used by millions of businesses. When a customer pays on an e-commerce site, the site never touches the customer's card. It sends the card details directly to Stripe's API, which handles tokenization, communicates with the card network, and returns a success or failure response. Stripe's webhooks then notify the merchant's system of the outcome so orders can be fulfilled.
Google Maps Platform — When you open a restaurant app and see a map with directions, that map is not built by the restaurant app. It is Google Maps rendered through the Maps JavaScript API or the Maps Static API, with the restaurant's markers and routing data layered on top. Google charges per API call beyond the free tier.
Twilio — The communications API behind SMS messages from hundreds of thousands of businesses. When you receive a text message saying "Your order has shipped," that message was almost certainly sent via Twilio's Messaging API. The business's system calls Twilio's API with the recipient's number and the message text; Twilio routes it to the appropriate mobile carrier.
OpenAI API — Applications built on GPT models do not contain the AI model themselves. They send prompts to OpenAI's API and receive generated text back. Every ChatGPT-powered tool, AI writing assistant, or coding helper using GPT models is a client of this API, paying per token for the generation.
Weather APIs — Services like OpenWeatherMap or Tomorrow.io provide weather data via API. Any weather app, any website that shows a local weather widget, any alert system that triggers when rain is forecast — all of these are API consumers calling a weather data provider.
API Design Principles Worth Knowing
For anyone building APIs or evaluating them:
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 calls and ISO 8601 strings in others, is painful to work with. Every inconsistency is a trap for developers.
Versioning matters for public APIs that cannot break existing consumers when they change. Common approaches include URL versioning (/v1/users, /v2/users) or header versioning. Without versioning, any change risks breaking clients.
Idempotency means that making the same request multiple times has the same effect as making it once. This is critical for operations that involve money or state changes, where network failures might cause ambiguity about whether a request was processed. Stripe's API requires clients to send a unique Idempotency-Key with payment requests so that if a request is retried, it is not processed twice.
Rate limiting protects providers from abuse and runaway clients. Well-designed rate limit responses include headers that tell clients how many requests they have remaining and when the limit will reset, rather than just returning an error.
Clear error messages that explain not just what went wrong but how to fix it dramatically reduce developer frustration and support load.
Why APIs Matter Beyond Software Development
APIs have changed 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 call.
Stripe built a billion-dollar business by making one thing — payment processing — excellent and exposing it via a clean API. Twilio did the same for communications. Sendgrid for email. Mapbox for maps. This model enables startups to build products in days that would have taken years to build from scratch by purchasing commodity infrastructure as a service and focusing engineering effort on their specific differentiator.
For non-engineers, understanding APIs matters because:
- Product decisions often depend on what APIs exist and what they cost
- Security decisions rest on understanding authentication and key management
- Partnership decisions frequently involve API integrations
- Data decisions are shaped by what APIs can provide and what the terms of service allow
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 organizations that run on software.
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.