REST - Resource Naming

REST can help a lot when we talk about integration, however not used correctly, it could bring future problems. This article will talk about some of the best practices for creating a REST API.

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.

 /orders 

This 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}/items

Using 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/