RESTful URLs and folders

Question

On the Microformats spec for RESTful URLs:

GET /people/1
return the first record in HTML format

GET /people/1.html
return the first record in HTML format

and /people returns a list of people

So is /people.html the correct way to return a list of people in HTML format?

Answer 1

It says that GET /people/1.json should return the first record in JSON format. - Which makes sense.

Answer 2

You have the right idea. Both /people and /people.html would return HTML-formatted lists of people, and /people.json would return a JSON-formatted list of people.

There should be no confusion about this with regard to applying data-type extensions to "folders" in the URLs. In the list of examples, /people/1 is itself used as a folder for various other queries.

Answer 3

If you just refer to the URL path extension, then, yes, that scheme is the recommended behavior for content negotiation:

• path without extension is a generic URL (e.g. /people for any accepted format)
• path with extension is a specific URL (e.g. /people.json as a content-type-specific URL for the JSON data format)

With such a scheme the server can use content negotiation when the generic URL is requested and respond with a specific representation when a specific URL is requested.

Documents that recommend this scheme are among others:

• Cool URIs don't change
• Cool URIs for the Semantic Web
• Content Negotiation: why it is useful, and how to make it work

Answer 4

URIs and how you design them have nothing to do with being RESTful or not.

It is a common practice to do what you ask, since that's how the Apache web server works. Let's say you have foo.txt and foo.html and foo.pdf, and ask to GET /foo with no preference (i.e. no Accept: header). A 300 MULTIPLE CHOICES would be returned with a listing of the three files so the user could pick. Because browsers do such marvelous content negotiation, it's hard to link to an example, but here goes: An example shows what it looks like, except for that the reason you see the page in the first place is the different case of the file name ("XSLT" vs "xslt").

But this Apache behaviour is echoed in conventions and different tools, but really it isn't important. You could have people_html or people?format=html or people.html or sandwiches or 123qweazrfvbnhyrewsxc6yhn8uk as the URI which returns people in HTML format. The client doesn't know any of these URIs up front, it's supposed to learn that from other resources. A human could see the result of <a href="/sandwiches">All People (HTML format)</a> and understand what happens, while ignoring the strange looking URI.

On a closing note, the microformats URL conventions page is absolutely not a spec for RESTful URLs, it's merely guidance on making URIs that apparently are easy to consume by various HTTP libraries for some reason or another, and has nothing to do with REST at all. The guidelines are all perfectly OK, and following them makes your URIs look sane to other people that happen to glance on the URIs (/sandwiches is admittedly odd). But even the cited AtomPub protocol doesn't require entries to live "within" the collection...