6

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)

JohnDoe
  • 2,422
  • 5
  • 29
  • 44

2 Answers2

4

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.

Community
  • 1
  • 1
Steve Michelotti
  • 5,223
  • 1
  • 25
  • 30
  • Thank you for this explanation! It filled the conceptual gap I had with REST "design principles". Wasn't aware of HATEOAS but I like the attitude. – JohnDoe Mar 14 '11 at 16:34
0

There are few REST best practices to be followed when designing a REST API

  1. Abstract vs Concrete
  2. CRUD Operations
  3. Error Handling
  4. API Versioning
  5. Filtering
  6. Security
  7. Analytics
  8. Documentation
  9. Stability and Consistency
  10. URL Structure

Read More

Techie
  • 44,706
  • 42
  • 157
  • 243