Your First API Interaction: A Hands-On Walkthrough

Theory is essential, but nothing beats learning by doing. In this lesson, we will walk through interacting with a real, free, public API step by step. You will make live API calls, read real responses, and start building the muscle memory that separates beginners from practitioners.

We will use JSONPlaceholder — a free online REST API specifically designed for testing and learning.

---

1. Meet JSONPlaceholder

JSONPlaceholder (https://jsonplaceholder.typicode.com) is a free REST API that simulates a real backend. It provides fake data for:

Resource	Endpoint	Count
Posts	/posts	100
Comments	/comments	500
Albums	/albums	100
Photos	/photos	5000
Todos	/todos	200
Users	/users	10

This API supports all HTTP methods (GET, POST, PUT, PATCH, DELETE) and requires no authentication. It is perfect for learning.

Important note: JSONPlaceholder simulates responses. When you create or delete data, it returns the correct response but does not actually persist changes.

---

2. Method 1: Using Your Browser

The simplest way to make a GET request is to open a URL in your browser. Browsers make GET requests automatically when you navigate to a URL.

Try It Now

Open these URLs in your browser (just click or paste into the address bar):

1. Get a single post: https://jsonplaceholder.typicode.com/posts/1

You should see JSON data in your browser:

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae..."
}

2. Get all users: https://jsonplaceholder.typicode.com/users

This returns an array of 10 user objects with names, emails, addresses, and company info.

3. Get user 3's todos: https://jsonplaceholder.typicode.com/users/3/todos

This shows all todos belonging to user 3.

Browser Tip: Install a JSON Formatter

Raw JSON in browsers looks like a wall of text. Install a browser extension to format it:

• Chrome: "JSON Viewer" or "JSON Formatter"
• Firefox: Built-in (Firefox formats JSON automatically)
• Edge: "JSON Formatter for Edge"

---

3. Method 2: Using cURL in the Terminal

Open your terminal (Terminal on macOS, Command Prompt or PowerShell on Windows) and try these commands:

Get a Single Post

curl https://jsonplaceholder.typicode.com/posts/1

What you see:

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita..."
}

Get All Todos for User 1

curl "https://jsonplaceholder.typicode.com/todos?userId=1"

What you see: An array of 20 todo objects, each with an id, title, completed status, and userId.

Notice the quotes around the URL — they are needed when the URL contains ? or &.

Get a User's Complete Profile

curl https://jsonplaceholder.typicode.com/users/1

What you see:

{
  "id": 1,
  "name": "Leanne Graham",
  "username": "Bret",
  "email": "Sincere@april.biz",
  "address": {
    "street": "Kulas Light",
    "suite": "Apt. 556",
    "city": "Gwenborough",
    "zipcode": "92998-3874",
    "geo": {
      "lat": "-37.3159",
      "lng": "81.1496"
    }
  },
  "phone": "1-770-736-8031 x56442",
  "website": "hildegard.org",
  "company": {
    "name": "Romaguera-Crona",
    "catchPhrase": "Multi-layered client-server neural-net",
    "bs": "harness real-time e-markets"
  }
}

This is a rich, nested JSON object. Notice how address contains another object, and geo is nested inside address.

---

4. Exploring the API: A Guided Tour

Let us systematically explore the JSONPlaceholder API, resource by resource.

Tour Stop 1: Users

# How many users are there?
curl -s https://jsonplaceholder.typicode.com/users | python3 -m json.tool | head -5

There are 10 users. Each has a unique id from 1 to 10.

Tour Stop 2: Posts

# How many posts does user 1 have?
curl -s "https://jsonplaceholder.typicode.com/posts?userId=1" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))"

Output: 10. Each user has exactly 10 posts.

Tour Stop 3: Comments

# Get comments on post 1
curl https://jsonplaceholder.typicode.com/posts/1/comments

Each post has 5 comments. Comments have an id, name, email, body, and postId.

Tour Stop 4: Relationships

graph TD
    U[User] -->|has many| P[Posts]
    U -->|has many| A[Albums]
    U -->|has many| T[Todos]
    P -->|has many| C[Comments]
    A -->|has many| Ph[Photos]

    style U fill:#4f46e5,color:#fff
    style P fill:#0891b2,color:#fff
    style A fill:#0891b2,color:#fff
    style T fill:#0891b2,color:#fff
    style C fill:#059669,color:#fff
    style Ph fill:#059669,color:#fff

You can navigate these relationships through the API:

# User -> Posts
curl https://jsonplaceholder.typicode.com/users/1/posts

# Post -> Comments
curl https://jsonplaceholder.typicode.com/posts/1/comments

# User -> Albums
curl https://jsonplaceholder.typicode.com/users/1/albums

# Album -> Photos
curl https://jsonplaceholder.typicode.com/albums/1/photos

# User -> Todos
curl https://jsonplaceholder.typicode.com/users/1/todos

---

5. Making Changes: POST, PUT, PATCH, DELETE

Now let us go beyond reading data and try modifying it.

Create a New Post (POST)

curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Very First API Post",
    "body": "I just learned how to create data via a REST API!",
    "userId": 1
  }'

Response (201 Created):

{
  "title": "My Very First API Post",
  "body": "I just learned how to create data via a REST API!",
  "userId": 1,
  "id": 101
}

The server assigned id: 101 to your new post.

Update a Post (PATCH)

curl -X PATCH https://jsonplaceholder.typicode.com/posts/1 \
  -H "Content-Type: application/json" \
  -d '{"title": "I Updated This Title!"}'

Response (200 OK):

{
  "userId": 1,
  "id": 1,
  "title": "I Updated This Title!",
  "body": "quia et suscipit..."
}

Only the title changed. The body stayed the same because we used PATCH (partial update).

Delete a Post (DELETE)

curl -X DELETE https://jsonplaceholder.typicode.com/posts/1

Response (200 OK): Returns {} — the post has been deleted.

---

6. Exploring Other Free APIs

JSONPlaceholder is great for learning, but there are many other free APIs to practice with:

API	URL	What It Provides	Auth?
JSONPlaceholder	jsonplaceholder.typicode.com	Fake blog/user data	No
ReqRes	reqres.in	Simulated users with auth	No
PokéAPI	pokeapi.co	Pokemon data	No
REST Countries	restcountries.com	Country information	No
Dog CEO	dog.ceo/dog-api	Random dog images	No
Open Library	openlibrary.org/developers	Book data	No
GitHub API	api.github.com	Repository and user data	Optional

Try this fun one:

# Get a random dog image
curl https://dog.ceo/api/breeds/image/random

{
  "message": "https://images.dog.ceo/breeds/retriever-golden/n02099601_1234.jpg",
  "status": "success"
}

Or get all information about Pikachu:

curl https://pokeapi.co/api/v2/pokemon/pikachu

---

7. Building Your API Exploration Checklist

Every time you encounter a new API, follow this checklist:

graph TD
    A[New API] --> B[1. Read the documentation]
    B --> C[2. Find the base URL]
    C --> D[3. Check authentication requirements]
    D --> E[4. Make a simple GET request]
    E --> F[5. Examine the response structure]
    F --> G[6. Try query parameters]
    G --> H[7. Try POST/PUT/DELETE if allowed]
    H --> I[8. Check error responses]
    I --> J[9. Note rate limits]

    style A fill:#4f46e5,color:#fff
    style E fill:#059669,color:#fff
    style H fill:#d97706,color:#fff

Applying the Checklist

Let us apply this to the GitHub API:

1. Documentation: docs.github.com/en/rest
2. Base URL: https://api.github.com
3. Auth: Optional for public data, required for private repos
4. Simple GET: curl https://api.github.com/users/octocat
5. Response: JSON object with user profile data
6. Query params: curl "https://api.github.com/search/repos?q=rest+api&sort=stars"
7. POST: Requires authentication (token)
8. Error: curl https://api.github.com/users/nonexistent-user-xyz → 404
9. Rate limits: 60 requests/hour without auth, 5000 with auth

---

8. Common Beginner Mistakes

Mistake	What Happens	Fix
Forgetting https://	"Could not resolve host"	Always include the protocol
Not quoting URLs with ?	Shell interprets ? as glob	Use "double quotes"
Forgetting -X POST	Sends GET instead of POST	Always specify the method
Missing Content-Type header	400 or 415 error	Add -H "Content-Type: application/json"
Invalid JSON (missing comma)	400 Bad Request	Validate at jsonlint.com
Using single quotes in JSON	Parse error on Windows	Use \" for escaping on Windows

---

Summary and Key Takeaways

1. JSONPlaceholder is the perfect sandbox for learning REST APIs — free, no auth, full CRUD support.
2. You can make GET requests in a browser just by visiting a URL.
3. cURL gives you full control over HTTP methods, headers, and request bodies.
4. APIs expose related resources through nested URLs (e.g., /users/1/posts).
5. Practice with multiple free APIs to build confidence with different data structures.
6. Always follow the API exploration checklist when working with a new API.

---

Lesson Review Quiz

---

Practice Exercise: API Scavenger Hunt

Complete these challenges using the JSONPlaceholder API:

1. Find the email address of user 5:

curl https://jsonplaceholder.typicode.com/users/5

2. Count how many todos are completed for user 1:

curl -s "https://jsonplaceholder.typicode.com/todos?userId=1&completed=true" | python3 -c "import json,sys;print(len(json.load(sys.stdin)))"

3. Get all photos from album 2:

curl https://jsonplaceholder.typicode.com/albums/2/photos

4. Create a new comment on post 5:

curl -X POST https://jsonplaceholder.typicode.com/comments \
  -H "Content-Type: application/json" \
  -d '{"postId": 5, "name": "My Comment", "email": "me@test.com", "body": "Great post!"}'

5. Try getting a random dog image:

curl https://dog.ceo/api/breeds/image/random

You are now ready to dive deeper into HTTP in Module 2!