How do I structure a real-world API according to REST principles?

Question

We're reworking some APIs and are considering a REST-style approach, but we're realizing we aren't sure how to deal with certain situations (lists of resources with parameters that influence what is selected, etc.), or even how to effectively structure urls for resources that may be referred to by themselves but are conceptually subordinate to some other entity (think users/posts/comments, but with even more complicated relationships).

We've seen a lot of material on structuring REST APIs for simple cases, but what material is available that talks extensively about making these choices in more real-world scenarios?

Answer 1

If you can be more precise with you questions, there are plenty of people here who will attempt to help.

Otherwise, here are a few other resources that should be useful.

REST Discuss Mailing List

Rest Wiki

REST Cookbook

The best piece of advice I can give you though, is to stop thinking about how to structure URLs and focus on what links you are going to put in your representations. How to structure your URLs will be easy once you have figured out your media types.

Answer 2

First, it's important to note here that REST is an architecture, which means that it simply describes a strategy to follow for addressing and working with resources. It doesn't say how to implement that strategy, or even how to tell if somebody's being RESTful or not.

I also think you're overcomplicating things a bit. Here's a more precise answer for your two specific questions:

how to effectively structure urls for resources that may be referred to by themselves but are conceptually subordinate to some other entity (think users/posts/comments, but with even more complicated relationships)

Even if something is subordinate to something else conceptually, that doesn't necessarily matter for purposes of describing it. For example, let's use your blog example. A Blog may have many Articles, each of which may have one or more Pictures. At first crack, you might expect to be able to reference Pictures with something like:

http://api.example.com/articles/123/pictures/456

But notice that, since Pictures are resources themselves, there's nothing wrong with just doing:

http://api.example.com/pictures/456

(lists of resources with parameters that influence what is selected, etc.)

It's perfectly normal and acceptable to have parameters in a RESTful request. For example, say you want to get the first 500 pictures by date, starting from the twenty-fifth such picture. Your API might support something like this:

http://api.example.com/pictures?limit=500&offset=25&order=desc&by=date

Answer 3

I'll go ahead and assume we're talking about RESTful HTTP :)

This is how you would expose a "list of resources with parameters that influence what is selected":

/list?{search part}

Where the search part is some arbitrary string which you use to target a 'section' of the list resource.

The common way to do this (the way that browsers + html forms work) is to have key/value pairs for each parameter i.e:

/list?name1=fred&name2=dave&name3=matt

This convention for arranging your search part is not mandatory but you will find that following this pattern makes it easier to write HTML for your app. It would be no less valid in terms of HTTP and URI to use the following:

/list?fred,dave,matt

how to effectively structure urls for resources that may be referred to by themselves but are conceptually subordinate to some other entity

In REST there is no such thing as 'structured' URIs. A URI is simply a unique identifier - similarities and patterns in URI structure can make organising server side logic easier and make it 'pretty' for users to look at and figure out - but if you're doing REST there is no relationship between the following:

/foo

/foo/bar

.. unless you create a relationship with a hyperlink from one to the other. This rule of thumb is generally referred to as the 'hypertext constraint' or 'HATEOAS'.

Having said that - there's nothing wrong with 'prettying' up your URIs. Just be aware that (if you want to 'do REST') you should be linking everything together. Most APIs expose 'nested resources' like this:

/countries/england/cities/london

Hope that's helpful :-)

Answer 4

I am working on a show case for RESTful design and associated questions on my blog. I have not yet reached the sections that are probably more interesting for you but you can still start reading:

http://www.nordsc.com/blog/?cat=13 (bottom to top)

Jan