Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Nobody Understands REST or HTTP

blog.steveklabnik.com

Post reply on HN
Print view View original

61–70 of 72 posts

Re: Nobody Understands REST or HTTP

#61

Post by nirvdrum »

richardlblair wrote: post #56
almost wrote: post #23

Earlier quoted context omitted.

But how do you deal with the partial upgrade scenario? I might want to use a few of the new features in my client code but not have the time to upgrade (and test!) everything just yet. Of course version numbers in URLs can have their place too. But I think they should only really be used in situations where you have upgraded so much that the original URL space just makes no sense. And if you can avoid huge breaking u…

You also have to consider which of these 2 are easier to understand: api.example.com/v2/account or api.example.com/account Accept: application/vnd.steveklabnik-v2+json And I'm not talking about how easy it is for Developers to understand. I'm talking about how easy it is for Everybody to understand.

I'd argue the former is a lot easier/cleaner to document as well.

Re: Nobody Understands REST or HTTP

#62

Post by sopooneo »

almost wrote: post #8
sirclueless wrote: post #4

Earlier quoted context omitted.

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.

Re: Nobody Understands REST or HTTP

#63

Post by davedx »

drawkbox wrote: post #42
davedx wrote: post #35

Earlier quoted context omitted.

Can you elaborate on Unity not working well with headers? I've just started doing some web-stuff with it and found that so far it's been okay.

Services are a bit painful in Unity due to the WWW class: http://unity3d.com/support/documentation/ScriptReference/WWW... You can use System.Net.* but if you want support across iOS, Android, Web, and Desktop you need to use WWW. Which does not allow you to read or set headers. I have decent services working with it in JSON using LitJson but it is something they should work on and has prevented me from using headers…

Ahh yeah, I noticed that things are different from platform to platform. Thankfully we mostly work with the web player rather than the mobile platforms, so it's been pretty painless so far. I'm really loving using coroutines with the web stuff, they fit nicely together.

Thanks for the info :)

Re: Nobody Understands REST or HTTP

#64

Post by almost »

nirvdrum wrote: post #28
almost wrote: post #23

Earlier quoted context omitted.

But how do you deal with the partial upgrade scenario? I might want to use a few of the new features in my client code but not have the time to upgrade (and test!) everything just yet. Of course version numbers in URLs can have their place too. But I think they should only really be used in situations where you have upgraded so much that the original URL space just makes no sense. And if you can avoid huge breaking u…

The same way you'd handle it on a per-header basis . . . you just use the new API version in the URL where needed. Sorry, I feel like I must be missing something here.

You are a little. In a properly RESTful API you simply don't construct URLs most of the time. Instead you follow links. If you change the URL structure you break the links. If that's what you want then a version number in the URL makes sense, but in a properly RESTful API that's probably not what you want.

I think for a lot of people the reason they don't see the benefit of things from REST is they try to use them in isolation. You say "this is useless for my RPC style API!" and you are right.

Re: Nobody Understands REST or HTTP

#65

Post by almost »

sopooneo wrote: post #62
almost wrote: post #8

Earlier quoted context omitted.

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 det…

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.

Re: Nobody Understands REST or HTTP

#66

Post by almost »

jedberg wrote: post #30
almost wrote: post #6

Earlier quoted context omitted.

With a RESTful API you don't tend to need IDs most of the time, you just use URLs. So having all the versioning info in the URL is not so great, you change the version and suddenly all the URLs aren't valid anymore. But more important that is upgrading a version on an API may not be an all or nothing thing. You might want to start using the new features of the API on one resource type but you aren't ready to upgrade…

If I want to share a link to your API, and you're using accept headers for versioning, how do share that URL? I think that not only is using accept headers worse, I think it is flat out wrong. That's not what the accept header is for. It's for client specific things only. The version of the API you need is NOT client specific.

It depends what you want to share though. Are you sharing the location of a resource or are you sharing a specific version of that resource?

If I'm viewing some resource in some client that supports version X and I send it to you and you view it in a client that supports version Y (maybe this happens automatically, maybe new versions are in the process of being rolled out, maybe your on the mobile client that hasn't been updated yet) isn't it better that my client gets a representation of it that it can understand?

(I don't think there's one answer for everything, I think both can make sense in different situations. But I think versioning via Headers can be very powerful and can interact well with of RESTful types of things you might want to do, it would certainly make no sense in an RPC style API)

Re: Nobody Understands REST or HTTP

#67

Post by almost »

richardlblair wrote: post #54
almost wrote: post #23

Earlier quoted context omitted.

But how do you deal with the partial upgrade scenario? I might want to use a few of the new features in my client code but not have the time to upgrade (and test!) everything just yet. Of course version numbers in URLs can have their place too. But I think they should only really be used in situations where you have upgraded so much that the original URL space just makes no sense. And if you can avoid huge breaking u…

How frequently do you think restful apis move to a new version? Typically you don't release a new version until you need to do significant changes to the entire layout of your api. In which case the old version is not even relevant. With this in mind, you would not want to promote using a new version of the api for one resource with an old version of the api for another resource. Just thinking about it sounds dirty.…

I think little upgrades happen all the time. And sometimes you need a way to handle those.

Re: Nobody Understands REST or HTTP

#69

Post by nirvdrum »

almost wrote: post #64
nirvdrum wrote: post #28

Earlier quoted context omitted.

The same way you'd handle it on a per-header basis . . . you just use the new API version in the URL where needed. Sorry, I feel like I must be missing something here.

You are a little. In a properly RESTful API you simply don't construct URLs most of the time. Instead you follow links. If you change the URL structure you break the links. If that's what you want then a version number in the URL makes sense, but in a properly RESTful API that's probably not what you want. I think for a lot of people the reason they don't see the benefit of things from REST is they try to use them in…

But, if you follow a link and that link is generated by the server, I still don't see how encoding a version number in the URL makes things any harder.

FWIW, I've made an effort to follow the purity of it, but the APIs I see that try to do true ReST are insanely obtuse. If you know of any real world case studies where a provider went from "fake" ReST to true ReST, I'd love to read it. The contrived examples are not helping me out in the comprehension department.

Re: Nobody Understands REST or HTTP

#70

Post by telent »

javascriptlol wrote: post #58
telent wrote: post #57

Earlier quoted context omitted.

See where I said "usually"? And where I said your experience is valid but don't assume it's universal? Right

I never said my experience was universal, nor did I imply it. So what's your point?

If "I've never heard a good argument", "a completely academic waste of time" and "why should anyone non-academic building actual systems care what it means" aren't implications that your experience is valid and others' experiences aren't, then I concede and am happy to admit that you have totally Won The Argument if it makes you feel better

In either case, I'm done here.

Post reply on HN