Hacker News new | comments | show | ask | jobs | submit login

What I've come to realise is that if you try to make an API of any sort, somebody, somewhere, will write a post about how you're defiling the HTTP protocol.

Totally true. For example, this author would have problem's with reddit's API, where you indicate that you are requesting JSON by adding .json to any URL. And you know what? The world doesn't come crashing down.

There's nothing wrong with doing that. A resource can have multiple URLs and multiple representations. That's fine, in the right circumstances.

You say that, but a lot of people scream bloody murder about it. And this exemplifies one of the major problems for people like me that are trying to learn how to create REST APIs and understand why to bother doing so in the first place. The problem is that even people who seem to know what they are talking about fundamentally disagree on many things. And Fielding's dissertation does not cover many implementation details. It's like interpreting the constitution trying to figure out how it should all happen in the real world.

Some of the points of contention:

(1) Should api version go in the URL or accept header?

(2) Should representation type go in the url or accept header?

(3) Are custom HTTP verbs okay?

(4) Should GET, POST, PUT and DELETE map one-to-one to CRUD? Most say no, but other seeming authorities say it's fine.

(5) Should you ever return a URL template, and a set of entity identifiers that can be plugged in, or should you only return the fully formed URLs?

(6) What is the difference between a URL and a URI? (And all you who say this one is dead simple and I'm an idiot for not knowing, see if your answers actually agree with each other)

(7) Are two different language translations of a document different resources, or are they different representations of the same resource?

(8) If two different language translations are just different representations of the same resource, how should the client indicate which version it wants?

And of course some people say that a few of these questions aren't even within the scope of REST anyway.

Some answers, may be wrong but this is how it makes sense to me:

1. Possibly both (the one in the URL being the version of the URL-space and the one in the Header being the more fine grained Representation Version).

2. It depends. For simplicity it often makes sense to put it in the URL. For more generality headers can be better.

3. No

4. They don't have to. They usually do though and it makes most sense when they do.

5. Fully formed URLs are simpler, so go with those if you can. But sometimes you'll need more.

6. URLs are a subset of URIs. All URLs are URIs. URLs give the location of the resource whereas URIs just have to identify it (but could also give the location of course.

7. It depends. I lean towards different but I'm no authority.

8. Using the Accept-Language header. But I'm guessing this is not always the best way to do things.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | DMCA | Apply to YC | Contact