WRT caching and query parameters — it affects it only in a minor way; it disallows a cache from using heuristics to determine freshness; i.e., it has to be explicit, such as with Cache-Control: max-age. Since I hate heuristics, I’d say this isn’t a bad thing.

The only reason you should concern yourself with URI design really is to look for concrete benefits like being able to use relative URIs easily. Making them human-readable and intuitive are again just nice-to-haves.

You could use, as you suggest, a json list of urls for a collection or, even more explicity, do something like:

{“urls”: ['./1', './2', ...]}

but this is NOT a standard.

Confront this with HTML, a standard that explicitly specifies the A tag with HREF attributes. A browser+human user can easily and completely infer API usage information as well as any HTML-aware automata (i.e. http://twill.idyll.org/) can be easily programmed for interaction without “customization” (I don’t have to explain that the links are to be found in the “urls” key).

HTML allows conveying all the API semantics without the need of out of band documentation (i.e. the documentation of the specific Rest API)

JSON then could only be useful for “leaf” information…

Query parameters are actually part of the URL, so each different set of query parameters is actually a new resource and has to be cached separately. If this turns out to be a problem in the real world, try stabilizing your query parameters — sort your query parameters alphabetically for example, and refuse to serve requests without sorted query parameters. Also, make sure to move the pieces that are specifying the resource out of the query parameter into the path part and reserve the query parameters for alternate “views” such as sort by descending or another “view transform” like that.

And if you are tempted to use session ids in query parameters — sessions are just gross and shouldn’t be used. Ever. If you need to store some data that is scoped by some time interval or some other logical interval such as the duration of using a shopping cart, PUT a new resource at the beginning of the session and arrange to have DELETE called after the session times out. Then just link to it from the page where the session was created. You don’t really have to literally do the PUT if you use a technique like encrypting data into the url, since all you have to do is give out the encrypted url and if it decrypts again later, you know that the resource really should exist.

As you mention, having documents that contain links lets you ignore the format of the url. A link is a link. It’s nice to have links that are human parse-able, but it’s only nice from the standpoint of the humans learning about the structure of the system. When we added some REST-style resources to Second Life, the first thing we did was bootstrap a single url into the legacy login and teleport protocols — the “seed capability”. This was simply a resource which had named links to other resources that agent could use. All of the actual links were just UUIDs. Since UUIDs are unguessable it was enough to just transmit all of the resources over HTTPS and the capabilities would stay secure, while at the same time allowing extensibility from any of the resources in the graph without any other part of the system knowing.

I do think we need some more widely supported content types for common things. There are plenty of content types for various things lying around like iCal, so it’s probably just a matter of important services supporting useful content types, like we are seeing lots of services usefully provide RSS and ATOM representations of certain resources. Library support in a number of languages is also important, but since many formats are based on xml (or perhaps new formats could be based on json instead?) this may not be much of an issue.

Great post.

Yes; most JSON structures are dictionaries so the trick is to give those dictionaries a URL and treat each key/value as RDF property/values. But I still think it could be tricky to do. For adoption purposes it’s probably optimal to not say it’s RDF; the “no notation with denotation” crowds (Atom, JSON, uF) tend to have issues imvho with RDF tax.

not entirely true- query parameters can affect caching.

“if you can’t use a crappy URL structure with that same API then probably something is wrong with that API.”

Right. So in the AtomPub world we love service documents and the link construct. Clients never need to know URL structure. Except where they do and we revert to documenting parameters (like google charts) or using domain specific discovery languages (like opensearch)

But I think Dave Johnson caught flak here for no good reason and I find both of Roy’s posts lacking to some extent. Something like “Do a GET /articles/{id} to get the representation of a specific article.” is a perfectly good way to explain an “API” to a developer or an implementor. Lesson – don’t confuse explanation with specification. Alternatively, try to define an API for a developer or an implementor, without referring to methods, url structures or response codes. It’s hard to do well.

The real problem – calling these things “APIs” is confusing the heck out of a lot of people.