Introduction to REST APIs

# CHAPTER 1

Introduction to REST APIs #

"REST API" has drifted, in common usage, to mean roughly "an API that speaks JSON over HTTP." That is not what the term means, and the gap between the two causes a surprising amount of confusion.

REST — Representational State Transfer — comes from Roy Fielding's 2000 doctoral dissertation, written while he was helping design HTTP itself. It is an *architectural style*: a set of constraints that, taken together, produce systems which scale well and stay maintainable as they grow. It is not a protocol, not a specification, and not a library you install.

The constraints are the substance. Communication is stateless, so any server can handle any request without remembering previous ones — which is precisely what lets you put twenty servers behind a load balancer. Everything is modelled as a *resource* identified by a URL, and manipulated through HTTP's existing verbs rather than through method names invented per API. Responses declare their own cacheability. The client is decoupled from the server's internal structure.

Get those right and you inherit HTTP's entire supporting infrastructure — caching proxies, CDNs, standard status codes, existing tooling — for free. Get them wrong and you have a JSON-over-HTTP API that calls itself RESTful, which is common, occasionally defensible, and worth being able to recognise for what it is.

This chapter covers the constraints and the reasoning behind each. The chapters that follow turn them into concrete design decisions about URLs, verbs, status codes and versioning.

1. Beginner-Friendly Explanation #

1. 1. The Client (You): You know what you want to eat, but you cannot walk into the kitchen to cook it yourself. You must ask someone.

1. 2. The Server (The Kitchen): The kitchen has the ingredients and the chefs to prepare the food, but they don't know what you want.

1. 3. The API (The Waiter): You need a messenger. You give your order (the Request) to the Waiter. The Waiter carries your order to the kitchen. The kitchen prepares the food. The Waiter brings the food (the Response) back to your table.

An API (Application Programming Interface) is the waiter. It is a set of rules that allows two completely different computer programs to talk to each other safely and predictably.

2. What is a REST API? #

If an API follows the strict rules of REST, it is called a RESTful API. REST uses standard internet protocols (HTTP) and relies heavily on standardized URLs to represent "Resources" (like Users, Posts, or Products) rather than actions.

3. Why APIs Matter #

• You might have a React web app, an iOS app, and an Android app.

• Instead of writing three different backend databases, you write ONE REST API.

• The iOS app, Android app, and React app all send requests to the exact same API to fetch raw data, and then each app formats the data to look beautiful on its specific screen.

4. Real-World API Examples #

• Twitter/X API: Allows developers to write a Python script that automatically posts a tweet at 9:00 AM every day without opening the Twitter website.

• Stripe API: Allows an independent shopping website to process credit cards safely without having to build a bank.

• Google Maps API: Allows Uber to embed a map directly into their app.

5. Mini Project: A Simple Conceptual API Endpoint #

The Request (From Frontend to Backend):

GET https://api.mywebsite.com/users

The Response (From Backend to Frontend): The server doesn't return HTML. It returns raw, structured text data, usually in JSON (JavaScript Object Notation) format.

{
  "status": "success",
  "data": [
    { "id": 1, "name": "John Doe" },
    { "id": 2, "name": "Jane Smith" }
  ]
}

6. API Workflow #

1. 1. The Frontend triggers an event (e.g., User clicks "Load Friends").

1. 2. The Frontend creates an HTTP Request targeting a specific URL endpoint.

1. 3. The Backend receives the request, queries the database, and formats the data into JSON.

1. 4. The Backend sends the HTTP Response back.

1. 5. The Frontend receives the JSON data and uses JavaScript to update the screen.

7. Best Practices #

• Embrace RESTfulness: Treat your API as a collection of nouns (resources), not verbs (actions). A good REST API URL is /api/users. A bad API URL is /api/get_all_users_now. We will explore this deeply in Chapter 5.

8. Common Mistakes #

• Confusing APIs with Databases: Beginners sometimes think an API *is* a database. It is not. The database is the vault storing the data. The API is the security guard standing in front of the vault, enforcing rules and passing approved data back and forth.

9. Exercises #

1. 1. Using the restaurant analogy, explain the roles of the Client, the Server, and the API. Why can't the Client just access the Server directly?

10. Coding Challenges #

• Challenge: Open a new tab in your web browser and navigate to exactly this URL: https://jsonplaceholder.typicode.com/users. This is a free, public testing API. Look at the text that appears on your screen. You just made an HTTP GET request to a REST API! Notice how the data is structured with curly braces {} and square brackets []?

11. MCQs with Answers #

12. Interview Questions #

• Q: Define a REST API in your own words. Explain the primary architectural benefit of separating the frontend (Client) from the backend (API) in modern web development.

• Q: Explain the difference between an API and a Database. Why do we need the API layer in between the client and the data?

13. FAQs #

14. Summary #

15. Next Chapter Recommendation #