Top 10 REST API Verbs: A Complete Guide
Looking for a Postman alternative?
Try APIDog, the Most Customizable Postman Alternative, where you can connect to thousands of APIs right now!
II. Best Practices for Designing REST APIs
The design of a REST API plays a crucial role in its usability and effectiveness. It is essential to follow best practices to ensure that the API is meaningful, easy to extend, and backward compatible. In this section, we will discuss some of the top best practices for designing REST APIs.
A. Use Nouns Instead of Verbs in Endpoint Paths
A common mistake when designing REST APIs is using verbs in the endpoint paths. Instead, it is recommended to use nouns that represent the entity being retrieved or manipulated. The HTTP request method already indicates the action being performed. For example, instead of using /getUsers or /deleteUser, use /users or /users/{id} respectively. This makes the API more intuitive and easier to understand.
B. Understand the Semantics of HTTP Methods
Each HTTP method (GET, POST, PUT, DELETE, etc.) has a specific semantic meaning. It is important to understand these semantics and use the appropriate HTTP method for each action. For example, GET is read-only and should not change the state of the resource, while PUT is used for full updates and DELETE is used for deletion. By adhering to the semantics of HTTP methods, the API becomes consistent and predictable.
C. Always Make the Endpoint Name Plural
When designing REST APIs, it is a best practice to use plural nouns for naming collections. This is in line with the language used in databases, where tables are typically named in the plural form. For example, use /users to represent all users and /users/{id} to represent a specific user. This helps to maintain consistency and make the API more intuitive.
D. Use Hierarchical Objects or Relations between Objects
In some cases, resources have relationships with each other. It is important to design the API in a way that represents these relationships accurately. One way to achieve this is by using a hierarchical path structure that appends the nested resource to the parent resource. For example, if a user has multiple orders, the endpoint could be /users/{userId}/orders. This ensures that the nested resources in the API match the structure in the database.
E. Use the Query String for Optional and Complex Parameters
REST APIs should strive to keep the URL simple and focused on the resource being accessed or manipulated. For optional or complex parameters, it is recommended to use the query string. This avoids cluttering the URL with unnecessary information and makes it easier for clients to understand and construct requests. Use query parameters to specify filtering, sorting, or other optional parameters. For example, /users?country=US&sort=name.
F. REST API Versioning
As APIs evolve over time, there may be a need to introduce breaking changes. In such cases, it is important to have a versioning strategy in place. Versioning allows for releasing incompatible changes under a new version while maintaining backward compatibility with older versions of the API. There are different approaches to versioning, such as URI versioning (/v1/users), query string versioning (/users?version=1), header versioning (Accept-Version: v1), or media type versioning (Accept: application/vnd.myapp.users-v1+json). Choose a versioning strategy that works best for your API and communicate it clearly to your users.
G. Use HTTP Status Codes
HTTP status codes provide valuable information about the outcome of a request. It is important to respond to client requests with appropriate HTTP status codes. Use 2xx status codes for success, 4xx status codes for client errors, and 5xx status codes for server errors. By using the correct status codes, clients can understand the outcome of their requests without having to parse the response body. Keep the set of used status codes small and consistent throughout the API.
H. Provide Useful Error Messages
In addition to the HTTP status code, it is important to provide a useful and informative error message in the body of the HTTP response. This helps clients understand the cause of the error and provides guidance on how to resolve it. Include relevant information such as error codes, error descriptions, and suggested actions. Well-designed error messages can greatly improve the developer experience when using the API.
I. Documentation
Proper documentation is essential for every API. Documenting the API endpoints, request, and response structures, and any additional information that developers need to use the API is crucial. Good documentation provides clarity and context, enabling users to understand and use the API effectively. It is recommended to use tools such as Swagger or OpenAPI to generate interactive documentation. This not only makes it easier for users to explore and understand the API but also helps automate the validation of the API design.
Examples and Further Details for Each Best Practice
Let’s now dive into some examples and further details for each of the best practices discussed above.
A. Example for Using Nouns Instead of Verbs in Endpoint Paths
Consider the example of designing an API for managing a collection of books. Instead of using /getBooks or /deleteBook, it is more appropriate to use /books or /books/{id} respectively. This provides a cleaner and more intuitive API design.
B. Example for Understanding the Semantics of HTTP Methods
Suppose we are designing an API for a blog platform. When creating a new blog post, we would use the HTTP POST method, as it is the appropriate method for creating a resource. On the other hand, when retrieving a specific blog post, we would use the HTTP GET method, as it is the appropriate method for retrieving a resource.
C. Example for Making the Endpoint Name Plural
Continuing with the previous example, if we want to retrieve all blog posts, we would use the endpoint /posts instead of /post. The plural form ensures consistency with the language used in databases and makes the API more intuitive.
D. Example for Using Hierarchical Objects or Relations between Objects
Suppose we have an e-commerce website with products, categories, and subcategories. To design the API for retrieving all products under a specific category, we would use the endpoint /categories/{categoryId}/products. This reflects the hierarchical relationship between categories and products.
E. Example for Using the Query String for Optional and Complex Parameters
Imagine we have an API for searching hotels. We could use the query string to allow users to specify optional parameters for filtering the search results. For example, /hotels?city=New York&priceLessThan=200&sortBy=price. This makes the API more flexible and user-friendly.
F. Example for REST API Versioning
Let’s say we have an API for managing user profiles. If we introduce a breaking change, such as changing the structure of the profile object, we can release it under a new version. We could use URI versioning and have endpoints like /v1/profiles and /v2/profiles to maintain backward compatibility.
G. Example for Using HTTP Status Codes
Suppose we have an API for a shopping cart. When a user adds an item to the cart successfully, we would respond with the HTTP status code 201 (Created). On the other hand, if the item is out of stock, we would respond with the HTTP status code 409 (Conflict).
H. Example for Providing Useful Error Messages
In case of an error, such as a validation failure, it is important to provide a detailed error message. For example, if a user tries to create an account with an invalid email format, the error message could be “Invalid email format. Please enter a valid email address.” This helps users understand the cause of the error and how to rectify it.
I. Example for Documentation
To document our API effectively, we could use tools like Swagger or OpenAPI. These tools allow us to specify the API endpoints, request/response structures, and any additional information needed. The generated documentation provides a clear and comprehensive reference for users.
Conclusion
Designing REST APIs that follow best practices is crucial for creating robust and user-friendly APIs. By using nouns instead of verbs in endpoint paths, understanding the semantics of HTTP methods, making the endpoint name plural, using hierarchical objects or relations between objects, using the query string for optional and complex parameters, employing REST API versioning, using HTTP status codes effectively, providing useful error messages, and documenting the API properly, we can create APIs that are easy to understand, maintain, and use.
Looking for a Postman alternative?
Try APIDog, the Most Customizable Postman Alternative, where you can connect to thousands of APIs right now!
