Introduction:

Naming the endpoints of a REST API may seem like a simple task, but in reality, it is one of the keys to ensuring that your API is intuitive, easy to use and maintain. Imagine trying to navigate a system where the paths don't make sense or don't follow a logical pattern. It would be like trying to find your way in a city with no road signs. In this blog, we'll look at some best practices for naming your endpoints effectively, ensuring that your users and developers can interact with your API clearly and efficiently. At the end, you'll see a complete example that you can use as a practical exercise to apply what you've learned - read on to master the art of naming endpoints in REST APIs!

Contents:

1. Introduction.

2. Recommendations for naming your endpoints.

   1. Represent resources and not actions.
   2. Nested hierarchical structure.
   3. Use of clear and descriptive names.
   4. Consistency in the use of upper and lower case letters.
   5. Avoid file extensions.
   6. Endpoint naming formula.
   7. Complete REST API endpoint naming design example.

3. Acknowledgments.

Recommendations for naming your endpoints

When we design a REST API, we want it to be easy to understand and use. To achieve this we must follow some rules to name our URLs in a consistent way.

1. Represent resources and not actions (resources should be named in plural):

   You can fall into the trap of using actions or verbs when naming your endpoints such as:

   ‎

   How not to do it:

   GET /deleteBook/321

   GET /deleteBook?id=321

   POST /books/321/delete

   ‎

   Following the REST parameters, this is not well done, the correct way to do it for this example is that there is a resource called Books and through the HTTP methods we say the action we want to do as for example delete it (DELETE) like this:

   ‎

   How to do it right:

   DELETE /books/321

   ‎

2. Nested hierarchical structure:

   To maintain good consistency and coherence in our URLs, we must use a hierarchical structure that shows relationships between resources. Example:

   ‎

   How not to do it:

   /books?libraryId=123

   /comments?bookId=456

   ‎

   How to do it right:

   /libraries/123/books

   /books/456/comments

   ‎

3. Use of clear and descriptive names:

   Continuing with consistency in the naming of endpoints and knowing that verbs should not be used to name resources, remember to use names that clearly describe the resources.

   ‎

   How not to do it:

   /data

   /info

   ‎

   How to do it right:

   /users

   /products

   ‎

4. Consistency in the use of upper and lower case letters:

   How not to do it: Mixing upper and lower case inconsistently:

   /UserProfiles

   /Order_Details

   ‎

   How to do it right: Use lowercase letters and hyphens consistently:

   /user-profiles

   /order-details

   ‎

5. Avoid file extensions:

   It may seem very obvious, but let's not overlook the fact that we should not use file extensions in the resource name in our URL, we should let the content type be determined by the HTTP headers.

   ‎

   How not to do it:

   /users.json

   /orders.xml

   ‎

   How to do it right:

   /users

   /orders

As a more visual aid, following the conventions, we can use the following formula for naming our URLs:

‎

/{collection} /{store} /{document}/{controller}

‎

• Collection (plural): A set of resources:

  • /books

• Store (plural): Contains resources managed by the client (stores are not used as much):

  • /users/12/favorites

• Document (singular): An instance in a collection:

  • /books/2
  • /books/maths

• Controller (verb): Executable functions (usually when we use controllers the HTTP method we use is POST):

  • /users/12/reset-password

Complete example of how to name our endpoints:

In this section we will see a complete example of an api design, first we will see how a bad REST API design would look like and then its correction.

Note: Before seeing how a well designed REST API would look like, correct yourself the errors of the badly designed API and compare at the end. This way you will learn more!

‎

Poorly Designed API:

• Collection of books:

  • Obtain all books:

    • GET /getAllBooks

  • Create a new book:

    • POST /createBook

• A user's favorite books:

  • Get a specific user's favorite books:

    • GET /getUserFavorites?userId=12

  • Add a book to the favorites of a specific user:

    • POST /addFavorite?userId=12&bookId=123

• Specific Book

  • Obtain a specific book:

    • GET /getBookById?bookId=123

  • Update a specific book:

    • POST /updateBook?bookId=123

  • Delete a specific book:

    • POST /deleteBook?bookId=123

• Action/Controller in Specific Book

  • Mark a book as read:

    • POST /markBookAsRead?bookId=123

  • Request a loan extension:

    • POST /requestExtension?bookId=123

Problems with Bad Design

• Verbs in URLs: URLs should represent resources, not actions.

• Inappropriate use of HTTP methods: POST is used for update and delete, instead of PUT and DELETE.

• Use of query parameters: Query parameters (?bookId=123) are being used instead of resource identifiers in the path.

‎

Now we will see the API as it would be well designed.

‎

API well designed:

• Book Collection:

  • Obtain all books:

    • GET /books

  • Create a new book:

    • POST /books

• User Favorite Books

  • Get a specific user's favorite books:

    • GET /users/12/favorites

  • Add a book to the favorites of a specific user:

    • POST /users/12/favorites

• Specific Book

  • Obtain a specific book:

    • GET /books/123

  • Update a specific book:

    • PUT /books/123

  • Delete a specific book:

    • DELETE /books/123

• Action/Controller in Specific Book

  • Mark a book as read:

    • POST /books/123/mark-as-read

  • Request a loan extension:

    • POST /books/123/request-extension

Benefits of Good Design

• Clarity: URLs are clear and represent resources.

• Correct use of HTTP methods: GET, POST, PUT, and DELETE are used properly.

• Identifiers in the path: Resource identifiers are included in the path, not as query parameters.

• Logical structure: The hierarchical and logical structure facilitates the understanding and use of the API.

‎

Thus, by following the right structure and proper use of HTTP methods, the well-designed API is more intuitive, scalable and easy to maintain.

I hope this guide has provided you with the tools you need to design clear and consistent endpoints for your REST API. Good endpoint naming not only improves the user experience, but also facilitates the maintenance and scalability of your system. Remember that consistency and clarity are essential in API development. Don't forget to practice with the full example. Until next time, and happy coding!