The Resource-Oriented Architecture

Here’s the first point where the ROA builds upon the sparse recommendations of the REST thesis and the W3C recommendations. I propose that a resource and its URI ought to have an intuitive correspondence. Here are some good URIs for the resources I listed above:

1. http://www.example.com/software/releases/
   1.0.3.tar.gz
   
2. http://www.example.com/software/releases/
   latest.tar.gz
   
3. http://www.example.com/weblog/2006/10/24/0
   
4. http://www.example.com/map/roads/USA/AR/
   Little_Rock
   
5. http://www.example.com/wiki/Jellyfish
   
6. http://www.example.com/search/Jellyfish
   
7. http://www.example.com/nextprime/1024
   
8. http://www.example.com/next-5-primes/1024
   
9. http://www.example.com/sales/2004/Q4
   
10. http://www.example.com/relationships/Alice;Bob
    
11. http://www.example.com/bugs/by-state/open

URIs should have a structure. They should vary in predictable ways: you should not go to /search/Jellyfish for jellyfish and /i-want-to-know-about/Mice for mice. If a client knows the structure of the service’s URIs, it can create its own entry points into the service. This makes it easy for clients to use your service in ways you didn’t think of.

This is not an absolute rule of REST, as we’ll see in the “Name the Resources” section. URIs do not technically have to have any structure or predictability, but I think they should. This is one of the rules of good web design, and it shows up in RESTful and REST-RPC hybrid services alike.