01 — FUNDAMENTALS

What is an API?

Think of an API as a waiter in a restaurant. You (the client) look at a menu and tell the waiter what you want. The waiter takes your order to the kitchen (the server), and brings back your food (the response).

You (Client)

Browse the menu, place an order

API (Waiter)

Takes order, delivers response

Server (Kitchen)

Prepares data, sends it back

Definition

Application Programming Interface — a set of rules that allows different software applications to communicate with each other. It defines the methods and data formats that applications can use to request and exchange information.

Real-World Example

When you see a Google Map embedded in a weather app, that app is using the Google Maps API to request map data. The weather app never accesses Google's database directly — it asks through the API.

Common API Types

REST

Web standard, HTTP-based

SOAP

XML-based, enterprise

GraphQL

Query exactly what you need

gRPC

High-performance, Protobuf

02 — FUNDAMENTALS

Request & Response

Every API interaction is a two-part dance: you send a request, the server sends back a response. Let's see exactly what travels across the wire.

Live Flow Diagram

Client

Your browser/app

Server

API endpoint

Database

Data storage

Anatomy of a Request

                            HTTP Request
                            Client → Server
                        
GET /api/users/42 HTTP/1.1
                            Host: api.example.com
                            Accept: application/json
                            Authorization: Bearer tok_abc123

                            // No body for GET requests
                        

Anatomy of a Response

                            HTTP Response
                            Server → Client
                        
HTTP/1.1 200
                                OK
                            Content-Type: application/json
                            X-Request-Id: req_7f3a2b

                            {
                            "id": 42,
                            "name": "Alice Johnson",
                            "email": "alice@example.com"
                            }
                        

03 — FUNDAMENTALS

HTTP Methods

HTTP methods tell the server what action you want to perform. Think of them as CRUD operations mapped to verbs. Click each card to explore.

CRUD Mapping

GET

Read

POST

Create

PUT

Update

DELETE

Delete

GET

Retrieve Data

Fetch a resource or collection. Never modifies data.

Example
GET /api/users // List all users
                                GET /api/users/42 // Get user #42
                                GET /api/users?role=admin // Filter by
                                    query
                            

Safe

Does not alter server state. Can be cached.

Idempotent

Calling it 10x = same as calling once.

POST

Create Resource

Submit data to create a new resource. Has a body.

Example
POST
                                /api/users
                                Content-Type: application/json

                                {
                                "name": "Bob Smith",
                                "email": "bob@example.com",
                                "role": "user"
                                }
                            

Not Safe

Creates new data on the server.

Not Idempotent

Calling it 10x may create 10 resources.

PUT

Full Update

Replace an entire resource with new data.

Example
PUT /api/users/42
                                Content-Type: application/json

                                {
                                "name": "Alice Updated",
                                "email": "alice.new@example.com",
                                "role": "admin"
                                }
                                // ALL fields required — missing ones become null
                            

PATCH

Partial Update

Modify only the fields you send. Others stay unchanged.

Example
PATCH
                                /api/users/42
                                Content-Type: application/json

                                {
                                "role": "admin"
                                }
                                // Only "role" changes — name & email stay the same
                            

DELETE

Remove Resource

Delete a resource by its identifier.

Example
DELETE
                                /api/users/42
                                // User 42 is gone. Returns 204 No Content or 200 OK
                            

04 — FUNDAMENTALS

Status Codes

The server's way of telling you what happened. The first digit tells you the category — memorize these five families and you'll read any API response like a pro.

1xx

Informational

2xx

Success

3xx

Redirection

4xx

Client Error

5xx

Server Error

05 — STRUCTURE

Headers

Metadata that travels with every request and response. Headers control caching, authentication, content format, and more. Click any header to see its role.

06 — STRUCTURE

REST Architecture

Representational State Transfer — the most popular API design style. It's not a protocol or standard, but a set of constraints that make APIs predictable and scalable.

Resource Naming Conventions

Bad

/getUsers
                                /user/create
                                /User/42
                                /users/list
                                /deleteUser/42
                            

Good

/users
                                /users (POST)
                                /users/42
                                /users (GET)
                                /users/42 (DELETE)
                            

07 — PRACTICE

API Playground

Build a request and see what comes back. This uses a simulated API — no real server calls. Experiment freely.

Request Builder

Response

Response Body

// Response will appear here

Quick Try — Click to load