Hello! Welcome back to the final lesson of our "API Fundamentals" module.
In our previous lessons, we got our hands dirty with the tools of the trade, Postman and curl. You learned how to use the fundamental HTTP methods—GET, POST, PUT, and DELETE—to perform the four basic CRUD (Create, Read, Update, Delete) operations.
So far, we've focused on the how. Today, we'll focus on the why. A well-designed API isn't just a random collection of endpoints; it follows a set of design principles that make it predictable, consistent, and easy to use. This architectural style is known as REST (Representational State Transfer).
Your goal for this lesson is to learn how to identify RESTful patterns by examining a well-designed public API. We'll break down the core principles of REST, focusing on resource naming, the correct use of HTTP methods, and standard status codes. This knowledge is the final piece of the puzzle you need before we dive into building your own API with FastAPI.
1. What is REST?
At its core, REST is not a strict protocol or standard, but rather a set of architectural constraints for creating scalable, stateless, and uniform web services. Think of it as a widely accepted style guide for API design.
To get a clear overview of what REST is and why it's so fundamental to web and cloud applications, let's start with a short video.
This video from IBM Technology provides a great conceptual introduction to REST, explaining what it stands for and its key benefits.
Watch the first 3 minutes and 46 seconds of the video (00:00 - 03:46) to understand the definition of REST and how a URL is broken down into resources.
As the video explained, the key idea is to treat everything as a resource. A user, an AI model, a product, an order—these are all resources. A RESTful API provides a way to interact with these resources using standard HTTP methods.
2. The Core Patterns of a RESTful API
To identify if an API is RESTful, you need to look for three main patterns:
- Resource Naming: How the URLs (or URIs) are structured.
- HTTP Methods: How actions are mapped to HTTP verbs.
- Status Codes: How the API communicates the outcome of a request.
Let's break these down.
2.1. Resource Naming: Nouns, not Verbs
A fundamental principle of REST is that the URL should identify the resource, not the action being performed. The action is determined by the HTTP method.
This leads to a simple, powerful rule: Use nouns in your URLs, not verbs.
| Good (RESTful) | Bad (Not RESTful) |
|---|---|
GET /users |
GET /getAllUsers |
POST /users |
POST /createUser |
GET /users/123 |
GET /getUserById?id=123 |
DELETE /users/123 |
POST /deleteUser |
To see these rules in action, please study the following guide.
API Best Practices & Naming Conventions - GitHub
This document, 'API Best Practices & Naming Conventions,' offers a clear and practical set of rules for naming resources in a REST API. The 'Do's and Don'ts' tables are particularly useful.
Please read the following sections: Section 9: Do not use verbs in the URI Section 10: Use Plural nouns Section 14: Use Nesting on Endpoints to Show Relationships Section 15 & 16: Briefly review the advice on limiting nesting and using forward slashes. Focus on understanding the examples provided in the tables.
Key takeaways on resource naming:
- Use plural nouns for collections (e.g.,
/users,/orders). - Identify a specific item in a collection with its ID (e.g.,
/users/123). - Show relationships between resources using nesting (e.g.,
/users/123/posts). Keep nesting shallow (1-2 levels deep) to avoid overly complex URLs.
2.2. HTTP Methods: The Verbs for Your Nouns
As we've established, the URL is the noun and the HTTP method is the verb. In the previous lesson, you learned what each method does. In a RESTful design, they are applied consistently to resource URLs:
| Method | URL Example | Action |
|---|---|---|
GET |
/posts |
Retrieve a list of all posts. |
GET |
/posts/42 |
Retrieve the single post with ID 42. |
POST |
/posts |
Create a new post. |
PUT |
/posts/42 |
Fully update/replace post with ID 42. |
DELETE |
/posts/42 |
Delete the post with ID 42. |
This combination of noun-based URLs and standard HTTP verbs creates a predictable and powerful system for interacting with data.
2.3. HTTP Status Codes: Standardized Communication
The final piece of the puzzle is the response. A well-designed API uses standard HTTP status codes to tell the client what happened with its request. You've already seen 200 OK and 201 Created, but there are many others.
A good API provides more than just a 200 for success and a 500 for failure. It uses specific codes to give the client actionable feedback.
Common Status Code Families:
2xx(Success): The request was successful.200 OK: Standard success response forGETandPUT.
201 Created: The request resulted in a new resource being created (used withPOST).204 No Content: The request was successful, but there's no data to return (often used withDELETE).
4xx(Client Error): The client did something wrong.400 Bad Request: The server can't process the request due to a client error (e.g., malformed JSON).401 Unauthorized: The client must authenticate to get the requested response.403 Forbidden: The client is authenticated but does not have permission to access the resource.404 Not Found: The server can't find the requested resource.
5xx(Server Error): The server failed to fulfill a valid request.500 Internal Server Error: A generic error message when the server encounters an unexpected condition.
The following video discusses the importance of consistency and touches upon using standard status codes.
6 Easy Tips to Design an AWESOME REST API
In this clip from ArjanCodes, you'll see why consistency is crucial in API design and hear a quick tip about using standard HTTP status codes for error messages.
Watch from 03:45 to 05:15 to understand the importance of consistency, and then from 20:45 to 21:20 for a quick tip on using status codes.
3. Case Study: The GitHub API
Theory is great, but let's see how these patterns look in the real world. The GitHub API is a widely-used, well-designed RESTful API. The following article demonstrates how to interact with it using Python's requests library, which should be familiar to you.
As you go through it, your task is to act as a design critic. For each example, identify the RESTful patterns we've just discussed.
Getting Started with Github API. REST API v3 using Python - Medium
This article, 'Getting Started with Github API', provides practical Python examples for creating, deleting, and listing resources. It's a perfect case study for identifying RESTful patterns in action.
Read the sections 'How to read Github API documentation?' and 'Lets do some Coding and make API calls'. For each coding example (Create, Delete, List repositories), ask yourself: URL Structure: Is the URL a noun? Is it plural? (e.g., /user/repos) HTTP Method: Does the method (POST, DELETE, GET) match the action being performed? Response: The author mentions the success response for creating a repository is 201. Does this match what you've learned?
By analyzing the GitHub API, you can see how these principles come together to create an API that is logical and easy to understand. For instance, creating a repository involves a POST request to /user/repos, and listing them involves a GET request to /users/{username}/repos. This is REST in practice.
Conclusion
In this lesson, you've moved from the mechanics of API requests to understanding the philosophy behind a good API design. You now have a mental checklist to evaluate any API you encounter.
Here are the key takeaways:
- REST is an architectural style focused on resources.
- Resource Naming: URLs should contain nouns (usually plural) to identify resources (e.g.,
/articles,/articles/123). - HTTP Methods: Standard verbs (
GET,POST,PUT,DELETE) are used to perform actions on those resources. - Status Codes: The API uses standard codes (
2xx,4xx,5xx) to communicate the outcome of a request in a predictable way.
You have now completed the "API Fundamentals" module. You know how to consume an API and, just as importantly, you know what a well-designed API looks like.
In our next lesson, we will begin a new module: FastAPI First Steps. You'll take everything you've learned and apply it from the other side. We'll install FastAPI and Uvicorn, set up your first project, and create your very own API endpoint. Let's get ready to build