An API (Application Programming Interface) is a way for two programs to talk to each other. When you check the weather on your phone, the app sends a request to a weather API, which sends back the data. Your app doesn’t have weather stations — it asks someone who does.

That’s it. An API is a messenger between software.

A real example

You want to show a user’s GitHub profile on your website. You don’t have access to GitHub’s database. But GitHub has an API:

curl https://api.github.com/users/octocat

GitHub responds with:

{
  "login": "octocat",
  "name": "The Octocat",
  "public_repos": 8,
  "followers": 9847
}

Your website reads that JSON and displays it. You never touched GitHub’s database — you just asked their API nicely.

How APIs work (HTTP)

Most APIs use HTTP — the same protocol your browser uses. You send a request, you get a response.

The request has:

• A URL (where to send it): https://api.example.com/users
• A method (what to do): GET, POST, PUT, DELETE
• Headers (metadata): Content-Type: application/json
• Body (data, for POST/PUT): {"name": "Alice"}

The response has:

• A status code: 200 OK, 404 Not Found, 500 Server Error
• Headers: Content-Type: application/json
• Body (the data): {"id": 1, "name": "Alice"}

REST — the most common API style

REST (Representational State Transfer) is a set of conventions for designing APIs. Most APIs you’ll use are REST APIs.

The pattern: HTTP method + URL = action

Method	URL	What it does
GET	/users	List all users
GET	/users/1	Get user with ID 1
POST	/users	Create a new user
PUT	/users/1	Update user 1 (full replace)
PATCH	/users/1	Update user 1 (partial)
DELETE	/users/1	Delete user 1

Using an API with JavaScript

// GET — fetch data
const response = await fetch('https://api.example.com/users');
const users = await response.json();
console.log(users);

// POST — send data
const response = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Alice', email: 'alice@example.com' }),
});
const newUser = await response.json();

Using an API with Python

import requests

# GET
response = requests.get('https://api.example.com/users')
users = response.json()

# POST
response = requests.post('https://api.example.com/users', json={
    'name': 'Alice',
    'email': 'alice@example.com',
})
new_user = response.json()

Using an API with cURL

# GET
curl https://api.example.com/users

# POST
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'

For more cURL patterns, see the cURL cheat sheet.

HTTP status codes

The response includes a number that tells you what happened:

Code	Meaning
200	OK — request succeeded
201	Created — new resource created
400	Bad Request — you sent invalid data
401	Unauthorized — you need to log in
403	Forbidden — you’re logged in but not allowed
404	Not Found — that resource doesn’t exist
429	Too Many Requests — you’re being rate limited
500	Internal Server Error — the server broke

Full list: HTTP Status Codes cheat sheet

Authentication

Most APIs require authentication so they know who’s making requests.

API Key — a secret string you include in the request:

curl -H "X-API-Key: your-key-here" https://api.example.com/data

Bearer Token (OAuth/JWT) — a token you get after logging in:

curl -H "Authorization: Bearer eyJhbGci..." https://api.example.com/me

REST vs. GraphQL

	REST	GraphQL
Endpoints	One per resource (/users, /posts)	One endpoint (/graphql)
Data	Server decides what to return	Client specifies exactly what it wants
Over-fetching	Common (get 20 fields when you need 2)	No (request only what you need)
Learning curve	Lower	Higher

Most APIs are REST. GraphQL is popular for complex frontends (like Facebook, which created it).

Public APIs to practice with

• JSONPlaceholder — fake REST API for testing
• GitHub API — real data, no auth needed for public repos
• OpenWeather — weather data (free tier)
• PokeAPI — Pokémon data (fun for learning)

Next steps

1. Open your terminal and run curl https://api.github.com/users/octocat
2. Try it in JavaScript with fetch()
3. Build something small — a weather widget, a GitHub profile card
4. Learn about authentication when you’re ready for private APIs