Use nouns instead of verbs
Keep the URI simple and intuitive. This will leave the API with a easier understanding and better to work with. A good way to test if the API was written correctly is making sure it has only 2 base URIs. For example:
This will return a collection of orders.
/ordersThis can be used to GET (READ), POST (CREATE), PUT (UPDATE) or DELETE depending on the HTTP verb chosen.
/orders/{orderId}This would return a collection of items from that particular order.
/orders/{orderId}/itemsUsing URIs with a non consistent pattern (using verbs) could end up causing a bigger effort for developers to understand and use the API.
/getAllOrders /getOrderItems
Plural nouns
Being consistent, establishing patterns, when designing a API is very important. Another common guideline is using plural nouns. Observe that finding resources in REST can be compared to search for documents in a disk.
/documents //(this would bring a list of documents) /orders //(this would bring a list of orders)The difference between these two is that in REST, when getting a particular resource, id should be passed to use the resource, differently from the file system that file name would do it.
Concrete names rather than abstract
Sometimes developers look for a higher level of abstraction. Which sometimes bring less value for the API. Check out the next example:
Higher level of abstraction
/items /assets
Lower level of abstraction
/blogs /videos /articles
Using a higher level of abstraction, in this case, will not bring as much value for developers dealing with the api, while the lower level should allow the user to have a better understanding of the resources. This level, of course, should be defined accordingly to each cenario.
Also expose a manageable number of resources. Aim for concrete naming and to keep the number of resources between 12 and 24.
This is it for today, we will continue to talk about REST best practices in the next articles. Remember intuitive API uses plural rather than singular nouns and concrete rather than abstract names.
Source:
Web API Design - Brian Mulloy
http://apiux.com/2013/04/03/url-design-restful-web-services/
thanks ivan, it s very interesting
ReplyDeleteThanks a lot! You made a new blog entry to answer my question; I really appreciate your time and effort.
DeleteRESTful Web Services Corporate TRaining
RESTful Web Services Training In Chennai
Java Projects for Engineering Students of Computer Science
Project Centers in Chennai For CSE
Thanks for your feedback ramzi :)
ReplyDeleteGreat and Useful Article.
ReplyDeleteOnline Java Training | Java Training in Chennai | Java Training Institutes in Chennai | Online Java Course
Interesting Article
ReplyDeleteJava Web Services Training Online | Java Online Training
Java J2EE Online Training | Java Web Services Training in Chennai
Java Web Services Training in Chennai