Building, Debugging, and Final Project: Putting It All Together

Congratulations on making it to the final module! You have learned what APIs are, how HTTP works, the principles of REST, how to use cURL and Postman, JSON, status codes, parameters, and authentication. Now it is time to bring everything together.

In this module, you will learn to think like an API designer, master debugging techniques for when things go wrong, and complete a comprehensive final project that tests real public APIs.

---

1. Building a REST API: Conceptual Design

Before we debug, let us understand how a REST API is structured from the server's perspective. Even if you never build an API yourself, understanding the design will make you a much better API consumer.

Designing an API for a Bookstore

Let us design a complete REST API for an online bookstore:

Resources: Books, Authors, Categories, Reviews, Users, Orders

Endpoint Design

graph TD
    A["Bookstore API v1"] --> B["/books"]
    A --> C["/authors"]
    A --> D["/categories"]
    A --> E["/users"]
    A --> F["/orders"]

    B --> B1["GET /books - List all books"]
    B --> B2["GET /books/:id - Get a book"]
    B --> B3["POST /books - Add a book"]
    B --> B4["PUT /books/:id - Update a book"]
    B --> B5["DELETE /books/:id - Remove a book"]
    B --> B6["GET /books/:id/reviews - Get reviews"]
    B --> B7["POST /books/:id/reviews - Add review"]
    B --> B8["GET /books?category=fiction&sort=price"]

    C --> C1["GET /authors - List all"]
    C --> C2["GET /authors/:id - Get one"]
    C --> C3["GET /authors/:id/books - Author's books"]

    E --> E1["POST /users - Register"]
    E --> E2["GET /users/:id/orders - User's orders"]

    F --> F1["POST /orders - Place order"]
    F --> F2["GET /orders/:id - Order details"]
    F --> F3["PATCH /orders/:id - Update status"]

    style A fill:#4f46e5,color:#fff
    style B fill:#0891b2,color:#fff
    style C fill:#0891b2,color:#fff
    style E fill:#059669,color:#fff
    style F fill:#d97706,color:#fff

Complete Endpoint Table

Method	Endpoint	Description	Auth Required
GET	/books	List all books	No
GET	/books/:id	Get a specific book	No
POST	/books	Add a new book	Yes (Admin)
PUT	/books/:id	Update a book	Yes (Admin)
DELETE	/books/:id	Delete a book	Yes (Admin)
GET	/books/:id/reviews	Get reviews for a book	No
POST	/books/:id/reviews	Add a review	Yes (User)
GET	/books?category=fiction	Filter by category	No
GET	/books?sort=price&order=asc	Sort by price	No
GET	/books?page=2&limit=20	Paginated results	No
GET	/authors	List all authors	No
GET	/authors/:id	Get an author	No
GET	/authors/:id/books	Books by an author	No
POST	/users	Register a new user	No
POST	/auth/login	Get auth token	No
GET	/users/:id/orders	User's order history	Yes (Owner)
POST	/orders	Place a new order	Yes (User)
GET	/orders/:id	Get order details	Yes (Owner)
PATCH	/orders/:id	Update order status	Yes (Admin)

Example Request and Response

GET /books/42:

{
  "id": 42,
  "title": "Clean Code",
  "author": {
    "id": 7,
    "name": "Robert C. Martin"
  },
  "isbn": "978-0132350884",
  "price": 34.99,
  "category": "Software Engineering",
  "rating": 4.7,
  "reviewCount": 2847,
  "inStock": true,
  "publishedDate": "2008-08-01",
  "description": "A Handbook of Agile Software Craftsmanship"
}

POST /books/42/reviews:

{
  "rating": 5,
  "title": "Must-read for developers",
  "body": "This book changed how I write code. Every principle is practical and actionable.",
  "userId": 15
}

Response (201 Created):

{
  "id": 892,
  "bookId": 42,
  "rating": 5,
  "title": "Must-read for developers",
  "body": "This book changed how I write code. Every principle is practical and actionable.",
  "userId": 15,
  "createdAt": "2026-02-22T18:30:00Z"
}

GET /books?category=fiction&sort=rating&order=desc&page=1&limit=5:

{
  "data": [
    {"id": 10, "title": "To Kill a Mockingbird", "rating": 4.9},
    {"id": 23, "title": "1984", "rating": 4.8},
    {"id": 5, "title": "The Great Gatsby", "rating": 4.7}
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 150,
    "totalPages": 30
  }
}

---

2. Debugging REST APIs: A Systematic Approach

When an API call fails, most beginners panic and start randomly changing things. Professionals follow a systematic debugging process.

The Debugging Checklist

graph TD
    A[API Call Failed] --> B{Got a response?}
    B -->|No| C[Check Connection]
    B -->|Yes| D{Status Code?}

    C --> C1[Is the URL correct?]
    C1 --> C2[Is the server running?]
    C2 --> C3[Is there a firewall or VPN blocking?]
    C3 --> C4[Can you ping the host?]

    D -->|400| E[Check Request Body]
    D -->|401| F[Check Authentication]
    D -->|403| G[Check Permissions]
    D -->|404| H[Check URL Path]
    D -->|405| I[Check HTTP Method]
    D -->|422| J[Check Field Values]
    D -->|429| K[Wait and Retry]
    D -->|500| L[Server Issue - Report]

    E --> E1[Is JSON valid?]
    E1 --> E2[Are required fields present?]
    E2 --> E3[Are data types correct?]

    F --> F1[Is the token included?]
    F1 --> F2[Is it expired?]
    F2 --> F3[Is the header format correct?]

    H --> H1[Check for typos]
    H1 --> H2[Is the resource ID correct?]
    H2 --> H3[Is the API version correct?]

    style A fill:#dc2626,color:#fff
    style C fill:#d97706,color:#fff
    style E fill:#d97706,color:#fff
    style F fill:#d97706,color:#fff
    style H fill:#d97706,color:#fff
    style L fill:#dc2626,color:#fff

Issue 1: 400 Bad Request

Symptoms: The server rejected your request data.

Debugging Steps:

1. Validate your JSON at jsonlint.com or with jq:

echo '{"name": "John" "age": 30}' | jq .
# parse error: invalid character after value
# Fix: missing comma after "John"

2. Check required fields — Read the API documentation to see which fields are mandatory.

3. Check data types — Is age a number or accidentally a string?

# Wrong (age as string)
curl -X POST https://api.example.com/users \
  -d '{"name": "John", "age": "thirty"}'

# Right (age as number)
curl -X POST https://api.example.com/users \
  -d '{"name": "John", "age": 30}'

4. Read the error response — Most APIs tell you exactly what is wrong:

{
  "errors": [
    {"field": "email", "message": "email is required"},
    {"field": "age", "message": "must be a positive integer"}
  ]
}

Issue 2: 401 Unauthorized

Debugging Steps:

1. Is the token included?

# Wrong - no auth header
curl https://api.example.com/data

# Right
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/data

2. Is the format correct?

# Wrong - missing "Bearer" prefix
curl -H "Authorization: abc123" https://api.example.com/data

# Right
curl -H "Authorization: Bearer abc123" https://api.example.com/data

3. Is the token expired? Get a new one by logging in again.

4. Is the header name correct? Some APIs use X-API-Key instead of Authorization.

Issue 3: 404 Not Found

Debugging Steps:

1. Check for typos:

# Wrong
curl https://api.example.com/ursers/1  # "ursers" instead of "users"

# Right
curl https://api.example.com/users/1

2. Does the resource exist? The ID might be wrong or the resource might have been deleted.

3. Check the API version:

# Wrong version
curl https://api.example.com/v1/users/1

# Right version
curl https://api.example.com/v2/users/1

4. Check trailing slashes — Some APIs treat /users/1 and /users/1/ differently.

Issue 4: 500 Internal Server Error

This is the server's fault, not yours. But you can help by:

1. Simplifying your request — Send the minimum required fields to isolate the issue.
2. Checking the API's status page — Many APIs have a status page (e.g., status.github.com).
3. Trying again later — It might be a temporary issue.
4. Reporting it — Include the request you sent, the response, and any X-Request-ID header.

The Universal Debugging Tool: Verbose Output

When in doubt, use curl -v:

curl -v -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token123" \
  -d '{"name": "John", "email": "john@test.com"}'

This shows you:

• Exactly what was sent (method, URL, headers, body)
• Exactly what was received (status code, headers, body)
• Connection details (DNS, TLS, timing)

In Postman, use the Postman Console (Ctrl/Cmd + Alt + C) for the same level of detail.

---

3. API Documentation: How to Read It

Every good API provides documentation. Knowing how to read API docs is a critical skill.

What Good API Docs Include

1. Base URL: https://api.example.com/v1
2. Authentication: How to get and use an API key or token
3. Endpoints: List of all available URLs and methods
4. Request Parameters: Required and optional fields
5. Response Format: What the JSON response looks like
6. Error Codes: What each error means and how to fix it
7. Rate Limits: How many requests you can make
8. Examples: cURL or code samples

Reading an Endpoint Entry

A typical API documentation entry looks like this:

POST /api/v1/books

Description: Add a new book to the catalog.

Authentication: Bearer Token (Admin role required)

Request Body:
| Field       | Type    | Required | Description               |
|-------------|---------|----------|---------------------------|
| title       | string  | Yes      | The book title             |
| authorId    | integer | Yes      | ID of the author           |
| isbn        | string  | Yes      | ISBN-13 format             |
| price       | number  | Yes      | Price in USD               |
| category    | string  | No       | Category slug              |
| description | string  | No       | Book summary               |

Response: 201 Created
{
  "id": 43,
  "title": "New Book",
  "authorId": 7,
  "isbn": "978-1234567890",
  "price": 24.99,
  "createdAt": "2026-02-22T18:30:00Z"
}

Errors:
- 400: Missing required fields
- 401: Missing or invalid token
- 403: Not an admin user
- 409: ISBN already exists

Popular API Documentation Examples

Practice reading real API documentation:

• JSONPlaceholder: jsonplaceholder.typicode.com — The API we have been using
• GitHub REST API: docs.github.com/rest — Excellent documentation
• Stripe API: stripe.com/docs/api — Industry gold standard
• OpenWeatherMap: openweathermap.org/api — Great for beginners

---

4. Final Project

This is your chance to prove that you can work with REST APIs independently. You will test a real, public API using everything you have learned.

Project Overview

You will perform a complete API testing exercise using the JSONPlaceholder API and the GitHub API. You will use both cURL and Postman.

Part 1: JSONPlaceholder CRUD Operations

Complete all five CRUD operations:

1. CREATE — Add a new post:

curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Final Project Post",
    "body": "I completed the REST API course and can now make API calls confidently!",
    "userId": 1
  }'

Expected: 201 Created with the new post data including an assigned id.

2. READ — Get all posts by user 1:

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

Expected: 200 OK with an array of 10 posts.

3. READ — Get a specific post with its comments:

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

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

Expected: 200 OK for both. The comments response is an array of 5 comment objects.

4. UPDATE — Modify post 1:

curl -X PATCH https://jsonplaceholder.typicode.com/posts/1 \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated by REST API Course Student"
  }'

Expected: 200 OK with the updated post data.

5. DELETE — Remove post 1:

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

Expected: 200 OK with an empty object.

Part 2: GitHub API Exploration

Use the GitHub API to practice with a real-world API:

1. Get a public user's profile:

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

2. Search for repositories:

curl "https://api.github.com/search/repositories?q=rest+api+tutorial&sort=stars&order=desc&per_page=3"

3. Get a repository's details:

curl https://api.github.com/repos/typicode/json-server

4. Check rate limit status:

curl -s https://api.github.com/rate_limit | python3 -m json.tool

Part 3: Error Handling

Intentionally trigger and understand these errors:

1. Trigger a 404:

curl -s -o /dev/null -w "Status: %{http_code}\n" \
  https://jsonplaceholder.typicode.com/posts/99999

2. Check status codes with verbose output:

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

3. Test with invalid endpoints:

curl -s -o /dev/null -w "Status: %{http_code}\n" \
  https://jsonplaceholder.typicode.com/invalid-endpoint

Part 4: Postman Collection

Build a complete Postman collection with:

1. Collection name: "REST API Course - Final Project"
2. Variable: baseUrl = https://jsonplaceholder.typicode.com
3. Requests (organized in folders):

Folder	Requests
GET Requests	Get all posts, Get single post, Get user posts, Get post comments
POST Requests	Create new post
PUT/PATCH Requests	Full update post, Partial update post
DELETE Requests	Delete post
GitHub API	Get user profile, Search repos

4. Export your collection as a JSON file.

---

5. What You Have Achieved

graph TD
    A[You Started Here] --> B[Module 1: What Is an API?]
    B --> C[Module 2: HTTP Basics]
    C --> D[Module 3: REST Fundamentals]
    D --> E[Module 4: cURL Mastery]
    E --> F[Module 5: JSON]
    F --> G[Module 6: Postman]
    G --> H[Module 7: Status Codes and Auth]
    H --> I[Module 8: Final Project]
    I --> J[You Are Here - API Professional!]

    style A fill:#dc2626,color:#fff
    style J fill:#059669,color:#fff
    style B fill:#0891b2,color:#fff
    style C fill:#0891b2,color:#fff
    style D fill:#0891b2,color:#fff
    style E fill:#0891b2,color:#fff
    style F fill:#0891b2,color:#fff
    style G fill:#0891b2,color:#fff
    style H fill:#0891b2,color:#fff
    style I fill:#4f46e5,color:#fff

After completing this course, you can now:

Skill	Level
Understand REST architecture	Confident
Read API documentation	Confident
Make API calls using cURL	Proficient
Test APIs using Postman	Proficient
Read and write JSON	Proficient
Interpret HTTP status codes	Proficient
Use query and path parameters	Proficient
Handle API authentication	Proficient
Debug common API issues	Proficient
Design REST API endpoints	Foundational

---

6. Where to Go Next

Now that you have a solid foundation, here are recommended next steps:

Practice with More APIs

API	URL	Focus
ReqRes	reqres.in	Simulated auth and user management
PokéAPI	pokeapi.co	Complex nested data
REST Countries	restcountries.com	Geographic data with filtering
OpenWeatherMap	openweathermap.org/api	Real-world API key usage
Spotify API	developer.spotify.com	OAuth 2.0 authentication

Learn to Build APIs

Ready to create your own REST APIs? Consider learning:

• Python + FastAPI: Modern, fast, automatic documentation
• Node.js + Express: JavaScript-based, huge ecosystem
• Go + Gin: High-performance APIs

Advanced Topics

• GraphQL: Alternative to REST for complex data fetching
• WebSockets: Real-time bidirectional communication
• gRPC: High-performance binary protocol for microservices
• API Gateway: Managing APIs at scale with tools like Kong or AWS API Gateway
• OpenAPI Specification: Standardized API documentation format

---

Summary and Key Takeaways

1. API design follows consistent patterns: noun-based URLs, HTTP methods for actions, and clear response formats.
2. Debugging is systematic: check the status code, read the error message, validate your request, and use verbose output.
3. API documentation is your best friend — learn to read it efficiently.
4. You now have the skills to consume any REST API in the world.
5. The next step is to build your own APIs and explore advanced patterns.

---

Final Review Quiz

---

Course Completion Checklist

Before you consider this course complete, verify that you can:

• Explain what a REST API is to a non-technical person
• Describe the HTTP request and response cycle
• List the five main HTTP methods and their purposes
• Make GET, POST, PUT, PATCH, and DELETE requests with cURL
• Read and write valid JSON
• Use Postman to test APIs visually
• Interpret HTTP status codes (200, 201, 400, 401, 404, 500)
• Use query parameters to filter API results
• Use path parameters to access specific resources
• Add authentication headers to API requests
• Debug common API errors systematically
• Read and follow API documentation
• Design REST endpoints conceptually

If you can check all of these boxes, you have successfully completed the Understanding REST APIs course. You are now equipped with practical API testing skills that are essential in modern software development.

Welcome to the world of APIs!