Design RESTful URI

Question

I am in the process of creating a RESTful API. I read

http://microformats.org/wiki/rest/urls

but this site doesn't give me enough "good" practice on designing my API. Specifically I will write an API (only GET methods that far) which will provide functions to convert geo-coordinates.

Example: A geohash is a single value representation of a coordinate, thus /convert/geohash/u09tvkx0.json?outputformat=latlong

makes sense. On the other hand /convert/latlong.xml?lat=65&long=13&outputformat=UTC requires two input values.

See my "question"? What makes a good API which requires more than one input parameter?

(Tried to "identify" good practice by "analysing" twitter & FF but failed)

Answer 1

In terms of being considered a "technically" correct REST URI, there is no difference between using query string parameters or not. In RFC 3986, it states:

The query component contains non-hierarchical data that, along with data in the path component (Section 3.3), serves to identify a resource

That's why you're having a difficult time finding a definitive "best practice". Having said that, many REST APIs do embed multiple parameters in the URI without using query strings. For exammple, to identify the make and model of a car, you'll see websites with URI's like this: cars.com/honda/civic. In that case it's very obvious the relationship between the 2 and so having everything in the URI is "hackable". It's also much easier to stick with a non-query string approach when you only have one parameter which is uniquely identifying the resource; but if it's something like a search query, then I'd probably keep it in the query string. This SO question has an interesting discussion about the different approaches as well.

In your example above, I would stick with the query string parameters. Although REST typically has more intuitive URLs, that's really not what REST is about. REST is more about hypermedia and HATEOAS.