5 Rules for Designing Clean REST APIs |

Hey readers,

I once had to work with an API where the endpoint to get a user’s data was /getUserData, but the endpoint to update it was /update_user_info. To delete a user, you had to POST to /deleteUser. It was a chaotic mess. Every time I needed to do something, I had to look up the exact, bizarre URL for that specific action.

That experience taught me that while you can make an API work in any number of ways, there’s a world of difference between a functional API and a good API.

A good API is predictable. It follows a set of conventions that, once you understand them, allow you to practically guess the endpoint you need. The most common set of these conventions is called REST (Representational State Transfer).

Think of a REST API as a well-organized library. This guide will give you the five core rules for designing your own clean, predictable, and easy-to-use REST APIs.

Rule 1: Use Nouns for Your URLs (Resources)

Your URLs should only ever refer to things, or resources. They should not contain actions or verbs. Your API is about exposing resources (like books, users, or products) to the client.

Analogy: In our library, the aisles are labeled “Fiction,” “History,” and “Science”—all nouns. They aren’t labeled “Go Find Fiction Books” or “Look At History Books.”
Good: /users, /products, /orders
Bad: /getUsers, /createNewProduct, /deleteOrder
Why it matters: This is the foundational principle of REST. The URL identifies the resource, and the HTTP verb (our next rule) identifies the action you want to perform on that resource.

Rule 2: Use HTTP Verbs to Specify Actions

Now that your URLs are all nouns, how do you tell the server what to do? You use the HTTP verbs we learned about in the last post.

Analogy: The librarian (the server) knows what to do based on your request. You can ask to get a book, add a new book to the collection, update a book’s record, or remove a book.
The Actions:
- GET /users -> Get a list of all users.
- GET /users/123 -> Get the user with ID 123.
- POST /users -> Create a new user.
- PUT /users/123 -> Update the user with ID 123.
- DELETE /users/123 -> Delete the user with ID 123.
Why it matters: By combining noun-based URLs with HTTP verbs, you create a predictable and powerful system. You don’t need to guess the URL for deleting a user; you just follow the pattern.

Rule 3: Use Plural Nouns

When naming your resources, always use plural nouns.

Analogy: The aisle in the library is labeled “Books,” not “Book,” because it contains a collection of them.
Good: /users, /products, /orders
Bad: /user, /product, /order
Why it matters: It keeps your API endpoints consistent. The URL /users represents the collection of all users. The URL /users/123 represents a single user from that collection. This consistent naming scheme makes your API feel logical and easy to navigate.

Rule 4: Return Proper Status Codes

Your API should be a good communicator. When a client makes a request, the response should include a status code that clearly indicates what happened.

Analogy: When you ask the librarian for a book, you get a clear response. “Here is the book” (200 OK), “I’ve added that new book to our collection for you” (201 Created), or “Sorry, I couldn’t find that book” (404 Not Found).
Key Status Codes to Use:
- 200 OK: For successful GET requests.
- 201 Created: For a successful POST request where a new resource was created.
- 204 No Content: For a successful DELETE request (there’s nothing to return).
- 400 Bad Request: The client sent invalid data (e.g., a missing field).
- 404 Not Found: The client asked for a resource that doesn’t exist.
Why it matters: It allows the client to know the result of its request without having to inspect the response body. This makes error handling on the frontend much easier.

Rule 5: Provide Nested Routes for Relationships

What if you want to get all the orders for a specific user? Your API should reflect this relationship through its URL structure.

Analogy: If you want to find books by a specific author, you might go to the “Authors” section of the library and then look up that author’s specific shelf.
Example: To get all orders for user 123, the endpoint should be: GET /users/123/orders
This is far more intuitive than something like GET /orders?userId=123.
Why it matters: Nested routes make the relationships between your resources clear and explicit right in the URL. It makes your API more expressive and easier to understand for other developers.

What’s the next move?

Challenge: Let’s design an API for a simple blog. The blog has posts and each post has comments. What would the RESTful URLs look like for the following actions?

Get all posts.
Create a new post.
Get a single post with an ID of 42.
Get all comments for post 42.
Create a new comment for post 42.

Think about the nouns, the verbs, and the relationships. Once you can map these out instinctively, you’re well on your way to designing clean APIs.

Thanks for reading!

Bou~codes and Naima from 10xdev blog.