REST: Way to map URLs to services/files ?

Question

In your humble opinion: what would be a best practice aproach to map REST URLs to services/files within one's architecture (let's assume MVC pattern here)?

Answer 1

The best way to map URLs to resources is dependent on what web framework you use to provide the REST service. Pick whatever url structure is easiest to manage with the tools you have.

The url structure should be completely opaque to the clients of your service so they should not care what they look like.

The most important thing in my opinion is that when you are looking at an URL it should be relatively easy to guess which controller on the server is going to respond to that URL. That will make development and debugging much easier.

Answer 2

In addition to Darrel's answer:

Make use of the hierarchical nature of HTTP URIs; think of every path segment as drilling down into the overall space of managed items (e.g. orders, customers). If at some point you need to 'index' into a collection along multiple dimensions (e.g. query) then use query string parameters:

/service/products/cars/japanese-cars/toyota/corola/&priceMin=2000&priceMax=5000

Note that (as darrel said) the structure should be opaque to the client. That means that the client needs to discover the parameters at run time (that is what forms or URI templates are for). Of course client and server need shared knowledge about the meaning of e.g. priceMin. That knowledge should be in some design time specification, for example the specification of a link relation. Maybe look at http://www.opensearch.org for detailed use case.

Also interesting is the host part of the URIs. If you might at some stage need to move parts of your services to another machine, design your URIs so that the relevant information is in the domain part. Then you can use simple DNS to route requests to different machines.

HTH, Jan