Every time you check the weather on your phone, log into a website with your Google account, pay for something online, or open a social media app — an API is doing the invisible work behind the scenes.
API stands for Application Programming Interface, and it is the single most important concept in modern software development. Despite the technical-sounding name, the underlying idea is remarkably simple: an API is a way for two pieces of software to talk to each other without either one needing to understand how the other one works internally.
This guide explains everything a beginner needs to know about APIs — what they are, how they function, the different types that exist, and how to make a real API call yourself.
What is an API? The Restaurant Analogy
Imagine you are sitting in a restaurant. You have a menu with a list of dishes you can order, but you have no access to the kitchen. You cannot walk into the back and cook your own meal. Instead, you tell a waiter what you want, the waiter takes your order to the kitchen, and the waiter brings your food back to you.
An API works exactly like that waiter:
- You are the application (a mobile app, a website, or another program).
- The waiter is the API — the messenger that carries your request to the server and returns the server’s response back to you.
- The kitchen is the server — the system that holds the data or runs the calculations you need.
- The menu is the API documentation — it tells you what requests you are allowed to make and in what format.
The key insight is this: you never need to know how the kitchen prepares your food. You just need to know what is on the menu, how to place an order, and what to expect when your meal arrives. APIs let different software systems collaborate without exposing their internal complexity to each other.
How Do APIs Actually Work?
APIs operate over the internet using a protocol called HTTP (Hypertext Transfer Protocol) — the same protocol your browser uses to load web pages. Here is how a typical API interaction happens:
The Request-Response Cycle
-
A client (your app) sends a request to a specific URL on a server. This URL is called an endpoint. The request includes an HTTP method (GET, POST, PUT, DELETE) that tells the server what action you want to perform.
-
The server processes the request. It validates your input, runs any necessary business logic or database queries, and prepares a response.
-
The server sends a response back to the client. The response includes a status code (indicating success or failure) and typically includes data in a format like JSON (JavaScript Object Notation).
A Real-World Example
Suppose you want to fetch the current weather in Berlin from a weather API. Your request might look like this:
GET https://api.openweathermap.org/data/2.5/weather?q=Berlin&appid=YOUR_API_KEYThe server responds with JSON data:
{ "city": "Berlin", "temperature": 18, "condition": "partly cloudy", "humidity": 65}Your application receives this JSON, parses it, and displays “18°C, partly cloudy” on the screen. You never needed to know anything about the weather station hardware, the server infrastructure, or the data processing pipeline — the API abstracted all of that away.
The Five Most Important HTTP Methods
Every API request specifies an HTTP method that describes the operation the client wants to perform:
| Method | Purpose | Example |
|---|---|---|
| GET | Retrieve data | Fetch a list of blog posts, get a user profile |
| POST | Create a new resource | Submit a new blog post, create a user account |
| PUT | Replace an existing resource entirely | Update a user’s full profile with new values |
| PATCH | Partially update an existing resource | Change only a user’s email address |
| DELETE | Remove a resource | Delete a blog post, cancel an order |
GET is by far the most common method you will encounter as a consumer of APIs. When you load a web page, search a database, or fetch weather data, your browser or app is making a GET request behind the scenes.
The Three Most Common Types of APIs
Not all APIs follow the same rules or structure. The three types you will encounter most often in the real world are REST, GraphQL, and WebSocket APIs.
1. REST APIs
REST (Representational State Transfer) is the most widely used API architecture on the internet today. Most major public APIs — including GitHub, Stripe, Twitter, and thousands of others — use REST. For a deeper technical reference, see the REST API glossary entry.
REST APIs follow a set of design principles that make them predictable, scalable, and easy to work with:
- Each resource is identified by a unique URL. For example,
/users/42represents user number 42, and/articles/100represents article number 100. - Standard HTTP methods map to CRUD operations. GET retrieves, POST creates, PUT/PATCH updates, DELETE removes.
- Stateless: each request contains all the information needed to process it. The server does not remember you between requests.
- JSON is the standard response format. Almost all modern REST APIs return data as JSON.
REST APIs are an excellent default choice for most projects. They are simple to understand, easy to cache, and have an enormous ecosystem of tools, documentation standards (like OpenAPI/Swagger), and testing platforms.
2. GraphQL APIs
GraphQL is a query language created by Facebook (Meta) in 2015 and released publicly in 2016. Unlike REST — which gives you one URL per resource — GraphQL exposes a single endpoint where you specify exactly which fields you want in your request.
Example GraphQL request:
query { user(id: 42) { name email posts { title publishedDate } }}This single query returns exactly the user data you need, including nested posts, in one network request. In REST, this same data might require two or three separate requests to different endpoints.
GraphQL excels when your application has complex, nested data requirements — such as dashboards that display data from many different sources simultaneously. It is less ideal for simple CRUD applications where REST provides a better default.
3. WebSocket APIs
REST and GraphQL both operate on a request-response model: the client sends a request, and the server sends a response. This works perfectly for most situations, but not for applications that need real-time, ongoing communication.
WebSocket APIs establish a persistent, bidirectional connection between client and server. Once the connection is established, either side can send messages at any time without the client needing to initiate a new request.
WebSocket APIs power:
- Live chat applications
- Multiplayer online games
- Real-time financial trading platforms
- Live collaborative editing tools (like Google Docs)
- Push notifications and live sports score updates
Real-World API Examples You Already Use
Most people use dozens of APIs every day without realizing it:
- Login with Google: When you click “Sign in with Google” on a website, your browser uses Google’s OAuth API to verify your identity and share your name and email with the site.
- Payment processing: When you buy something online, the website sends your payment details to the Stripe API (or another payment processor), which communicates with your bank and returns a success or failure status.
- Weather apps: Your weather app sends a GET request to a weather API (OpenWeatherMap, WeatherAPI) with your location and receives current conditions, forecasts, and alerts in return.
- Social media embeds: When a news site embeds a live tweet, it uses the Twitter/X API to fetch and display the tweet content in real time.
- Maps and directions: Every ride-sharing app, delivery service, and navigation tool uses mapping APIs (Google Maps API, Mapbox) to calculate routes and display maps.
API Terminology Decoded
When you start working with APIs, you will encounter a handful of recurring terms. Here are the most important ones:
- Endpoint: A specific URL where an API can be accessed. Each endpoint corresponds to a specific resource or action.
- Payload: The data sent in a POST or PUT request body, usually formatted as JSON.
- Status code: A three-digit number in the server’s response indicating the outcome. 200 = success, 404 = not found, 500 = server error.
- Authentication: A method to verify who is making the request. Common methods include API keys, OAuth tokens, and JWTs (JSON Web Tokens).
- Rate limiting: A restriction on how many requests a client can make within a given time window. If you exceed the limit, the API returns a 429 (Too Many Requests) status code.
- Timeout: The maximum time a client will wait for a server to respond before giving up. Poorly designed APIs with slow responses frustrate users and cause application errors.
For a structured overview of these concepts and more, explore the Software Development learning path.
How to Make Your First API Call
You do not need to be a programmer to try making an API call. The simplest way to test an API is using curl from a terminal, or by using a tool like Postman or the built-in developer tools in your browser.
Here is a real example using curl to fetch a random joke from a free public API:
curl https://official-joke-api.appspot.com/random_jokeThe server responds with:
{ "id": 42, "type": "programming", "setup": "Why do programmers prefer dark mode?", "punchline": "Because light attracts bugs."}In a real application, you would write code to make this request automatically, parse the JSON response, and display the joke to the user. The actual request format varies by programming language, but the underlying HTTP mechanics are identical.
APIs vs. Databases vs. SDKs: Clearing Up Common Confusions
Beginners often confuse these three related but distinct concepts:
- An API is a communication interface — a set of rules for how software talks to other software.
- A database is a storage system — where structured data lives (e.g., PostgreSQL, MySQL, MongoDB).
- An SDK (Software Development Kit) is a collection of tools, libraries, and code samples provided by a company to help developers use their API more easily in a specific programming language.
A helpful way to think about it: an API is the menu at a restaurant, an SDK is a cookbook that helps you interact with that menu more efficiently, and a database is the pantry where the ingredients are stored.
Frequently Asked Questions
Are APIs only used in web development?
No. APIs are used everywhere — mobile apps, desktop software, IoT devices (smart thermostats, connected cars), command-line tools, server-to-server communication, and embedded systems. Any time two software systems need to exchange data, an API is almost certainly involved.
Do I need to pay to use APIs?
Many APIs offer free tiers with usage limits suitable for learning and small projects. APIs like OpenWeatherMap, JokeAPI, and GitHub’s REST API all provide free access for basic use. Paid tiers unlock higher rate limits, more features, and production-grade support.
What is the difference between an API and a web service?
All web services are APIs, but not all APIs are web services. A web service is specifically an API that uses HTTP/HTTPS to communicate over the internet. APIs can also operate locally within a single machine (e.g., an operating system API that your code calls to read files or create windows).
How do I learn more about building APIs?
Start by learning how to consume existing APIs (like the ones mentioned in this guide), then progress to building your own using frameworks like Express (JavaScript), Flask (Python), or Spring Boot (Java). Understanding HTTP fundamentals — methods, status codes, headers, and authentication — is the essential foundation.
Related topics in the EduGlossary library: