REST 1:1 relation between resources

Question

I want to design a REST API which talks about bus stations.

E.g.

    GET /stations/1asca2dac34
    {
        name:  'Queen str.'
        lat: 50.45
        lon: 9.63
    }

My goal is now to represent the distances among stations. For example, the distance between station AAA and BBB is 5km. I am not an expert about REST design. What would be the best way to design such 1:1 relation?

I can think to the following solutions, but I am not sure whether they would fit to REST style.

1)

GET /distances/?station1=AAA&station2=BBB
{
    uid: 123
    station1=AAA
    station2=BBB
    km: 5
}

2)

GET /distances/AAA/BBB
{
    uid: 123
    station1=AAA
    station2=BBB
    km: 5
}

3)

GET /distances/123
{
    uid: 123
    station1=AAA
    station2=BBB
    km: 5
}

Answer 1

I would be using something like:

/stations/1asca2dac34/distance?from=432dscas

A client starting point could be /stations where he would get a list of all the stations (name, id, geolocation, kind of transports like bus, trains, etc.) that is known by your API.

From there on, by using HATEOAS you could provide the client links to all the underlying resources e.g.:

/stations/{id}/distance?from={id}

And perhaps some other station related stuff:

/stations/{id}/trains/timetable
/stations/{id}/trains/{train_id}/timetable
/stations/{id}/foobar

If you were to start out from /distances is kind of strange, because I for one would not be able to "guess" what kind of list it would return. Let me say up front that none of your options are wrong, but the bottom line is to make it sensible/"guessable" for your client consumer.

Agree with the question what Joshua Moore said. Does a "distances" resource make sense for your consumers or can everything be fanned out from one starting point (e.g. stations) because that is what your API is all/only about?

Answer 2

All of your examples are in fact REST styled URIs. It's a matter of opinion and applicability. Consider your target audience. #1 Makes a lot of sense since you are providing parameters for the query. #2 seems difficult for a consumer of your API to understand and #3 is even more abstract and assumes your consumer of your API knows the uid of the data.

You should be asking "Which of these best fits my consumers needs?"

Just my humble opinion.

Answer 3

I would suggest you have the starting point for on station be /stations/{id} and from there you can expose a link to /stations/{id}/distances. This second URI would list the distances from this station to all other stations, how you want to present that data is up to you. A final URI would take the form /stations/{id-a}/distances/{id-b} which can return a very simple figure. As a general rule, I would avoid using query strings if you can.

Answer 4

Another more RESTful possibility without query is to use URI delimiters.

GET /stations/{st_a;st_b}

With this design your URIs are easy and clean. The semicolon imply interchangable IDs (Richardson first book).

The return JSON is a simple value. The distance is I resource because it's a value from a computation.