Have you ever seen some API endpoints that contain a full sentence to access a resource? Some examples might be the following:
http://myshop.com/createNewProduct
http://myshop.com/deleteProduct
http://myshop.com/updateProduct
http://myshop.com/getProductDetail/P01
http://myshop.com/getProductComments/P01
The first thing to keep in mind is that you should never use verbs in your endpoints. Instead, use nouns in plural to refer to a resource into your API Endpoint. For example, the preceding example can be refactored to this:
The Rest way - Not recommended |
The RESTful way - Recommended |
http://myshop.com/createNewProduct http://myshop.com/deleteProduct http://myshop.com/updateProduct |
http://myshop.com/products |
http://myshop.com/getProductDetail/P01 | http://myshop.com/products/P01 |
http://myshop.com/getProductComments/P01 | http://myshop.com/products/P01/comments |
A good practice is not to extend the path depth higher than three paths. For example, use this:
http://myshop.com/products/P01/comments
Do that instead of the following:
http://myshop.com/products/details/P01/comments/today
If you want to extend your API to perform additional operations such as getting the first 10 messages published today, use query strings instead of paths. Consider this example:
http://myshop.com/products/P01/comments?day=today&count=10