7 ms·

After reading the title I was all set to come in here and complain about "REST" Nazis and make some comment about how real life situations tend to supersede str

After reading the title I was all set to come in here and complain about "REST" Nazis and make some comment about how real life situations tend to supersede strict adherence to conventions. But then I read the article and I have to admit this is a pretty egregious break with how REST services are supposed to work.

tptacek 16y ago
I came here to say the same thing. For those of you who aren't going to bother reading the Rdio API spec (I did, because there's something I want to hack together with it): the whole API is literally just a single URI that accepts a "method" param, where the method is a list of verbs like "get all tracks in this playlist" or "add a friend". There's a case to be made for relaxing the definition of REST to accept "just a bunch of URIs" APIs that don't follow the discoverability/transparency conventions of REST. But you can't call "here's a list of verbs" a REST interface. What you'd want to see in a Rdio REST interface would be: * /rdio/api/1/playlists * /rdio/api/1/playlist/foo * /rdio/api/1/artist/1 * /rdio/api/1/artist/1/tracks/2 &c &c &c. But, from what I can tell, none of the state inside Rdio's database is mapped to a URI.
- masklinn 16y ago
  > What you'd want to see in a Rdio REST interface would be: You should disclaim that these URLs could just as well be * /rdio?q=1&s=63 * /rdio?q=1&s=63-8 * /rdio/4E7?q=1 * /rdio/4E63?q=1 and still be part of a RESTful API.
  - swombat 16y ago
    No, those are not part of a REST API. You've got it wrong.
    - justincormack 16y ago
      Actually URLs are supposd to be opaque in rest so that is correct. Nice urls with http verbs but no hateos is what most "REST" APIs are though.
    - jamesbritt 16y ago
      Besides simply asserting the OP is wrong, perhaps you could explain what differences (aside from aesthetics) there are between /rdio/api/1/artist/1/tracks/2 and /rdio?api=1&artist=1&tracks=2 Routing code on the server can treat them as identical; is there anything about these two URL formats that would trip up a client? Does it change how caching might work?
      - nikcub 16y ago
        well I believe both are not correct. the idea is that you can build a generic 'REST' client and point it to almost anything that is a 'REST API' and it will work, in the same way we can now with web browsers a REST client will never figure out /api/1/ - which is why resources go in the path and query parameters go in as, well, query parameters :) from the server side you are right that modern front controllers and routing can make it all the same (heck, I can route resources to different subdomains, if I want), but a proxy does not know what the front controller logic is (ie. working backwards to what part is what).
        masklinn 16y ago
        > the idea is that you can build a generic 'REST' client and point it to almost anything that is a 'REST API' and it will work, in the same way we can now with web browsers That's a stupid idea. REST is built on two things: content types and resource location. The content types indicate the meaning and location of the resources, if the client does not understand the content-type, it can not do anything. You can not "build a generic 'REST' client and point it to almost anything that is a 'REST API' and it will work", that makes no sense. Indeed, that's not what web browsers do: the driver of the API on a website is the user, not the browser. > a REST client will never figure out /api/1/ - which is why resources go in the path and query parameters go in as, well, query parameters :) That's completely irrelevant.
        nikcub 16y ago
        > That's a stupid idea. REST is built on two things: content types and resource location. here is what my generic REST client looks like: * HTTP[s] * JSON * Atom and RSS * Caching layer some controller login in between all of these. I inherit this to implement simple models and controllers in the client and just tell it which resources I want (like fields in a database) how is that not a generic client? for twitter I have classes called users and statuses, with each method defined. for google I have similar classes. this all took minutes for me to get working - I thought that was the entire point of REST? read the original desertion, sec. 5.2.2 connectors: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_2 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch... > if the client does not understand the content-type, it can not do anything. generic doesn't mean understanding the payload, it means understanding the protocol
    - masklinn 16y ago
      Behold, the know-nothing. Sorry sir, I'm not wrong, those would be perfectly valid as part of a REST service, including as alternatives to tptacek's description. Readability of the URLs has nothing at all to do with RESTfullness. The only thing REST says about the data transmitted (the URL in this case) is that it's the container for the application's state, and most interpretations of this is that the URL is entirely opaque. And indeed, Fielding has suggested/explained this several times.
      - swombat 16y ago
        See http://en.wikipedia.org/wiki/Representational_State_Transfer http://en.wikipedia.org/wiki/Representational_State_Transfer Those are not REST because they are not resource-based. Correct REST: http://blah.com/widget/:id http://blah.com/widget/:id - GET, PUT, POST, DELETE How does that fit with your /rdio/4E7?q=1 ? Where's the resource? What is the id? What is q anyway? You can pass parameters with a ? in REST... for example, you might do GET http://blah.com/resource/123?format=xml http://blah.com/resource/123?format=xml But there's still a clearly identified resource which the GET is performed on. Sure, technically, by stretching things a bit, you could claim that /rdio?q=1&s=63-8 is a REST GET request for resource id "63-8". And, technically, you'd be right, much like technically, this is valid C: http://stackoverflow.com/questions/18642/what-is-the-most-unreadable-programming-language/18767#18767 http://stackoverflow.com/questions/18642/what-is-the-most-un... But just because it's valid doesn't mean it's in any way good. Those are horrible examples. So no, those URLs could not "just as well" be those nasty examples you give. They could, much more poorly, be those examples, and still be technically valid. By the same reasoning, "Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo" is just as good english as Shakespeare.
        Darrel 16y ago
        All query string parameters are used to identify the resource also. RFC 3986 states "The query component contains non-hierarchical data that, along with data in the path component (Section 3.3), serves to identify a resource within the scope of the URI's scheme and naming authority (if any)." There is absolutely no difference between path segments and query parameters from the perspective of resource identification.
- deleted 16y ago
  [deleted]
- nikcub 16y ago
  I don't like API version numbers in the URI. It implies that a resource is different just because you are using a newer version of the API. My own most recent implementations use Accept: and Content-Type to define version compatibility, which is what content negotiation is supposed to be about. Versioning in the old web API sense meant changing the way the protocol works, and REST will always be REST and the resources will always be resources. All that is likely to change between 'API versions' is formats, which you negotiate with headers, and adding new fields, which old clients can either ask not to get through content negotiation or can safely ignore.
  - Groxx 16y ago
    I can see it both ways. APIv2 is not the same resource as APIv1, so why send it to the same location? Similarly, APIv1/user/1 may very well not contain the same information as APIv2/user/1, so are they really the same resource? They likely refer to the same semantic resource, but if user/1 != user/1, they're not the same from a data standpoint, which is what APIs are generally used for.
    - nikcub 16y ago
      If version 1 of a resource is not a subset of version 2 of a resource, and they are not accessing the same record, then they should be separate resources what 'API' is signaling is what the client is capable of understanding, which is what content negotiation headers are for I think of it no different to the same resources for web browser consumption (for humans) - I don't place new designs of a website into /design1/ /design2/ etc.
      - jerf 16y ago
        Bear in mind the more things like "Well, you just have to properly use the content negotiation headers" you add to your API, the more the "simplicity" argument of REST goes out the window. I'm not sure I've ever seen really correct use of the content-negotiation headers and claiming it's a solution is dubious... sort of like how I'm still waiting to see proper use of XML Namespaces in the wild. They seem relatively simple to me but the evidence suggests strongly otherwise. That doesn't make REST "bad", but I think it does start to make the quasi-religious aspect of it less obviously correct.
pkulak 16y ago
I agree. I recently built an API for a project of mine and I decided to make it REST-like, but not use the HTTP method to distinguish actions. In some circumstances you can only use one (JSONP, for example), so I sacrificed some purity for "the real world". This seems like it goes a bit over the line, however.

tptacek 16y ago

I came here to say the same thing. For those of you who aren't going to bother reading the Rdio API spec (I did, because there's something I want to hack together with it): the whole API is literally just a single URI that accepts a "method" param, where the method is a list of verbs like "get all tracks in this playlist" or "add a friend". There's a case to be made for relaxing the definition of REST to accept "just a bunch of URIs" APIs that don't follow the discoverability/transparency conventions of REST. But you can't call "here's a list of verbs" a REST interface. What you'd want to see in a Rdio REST interface would be: * /rdio/api/1/playlists * /rdio/api/1/playlist/foo * /rdio/api/1/artist/1 * /rdio/api/1/artist/1/tracks/2 &c &c &c. But, from what I can tell, none of the state inside Rdio's database is mapped to a URI.

masklinn 16y ago
> What you'd want to see in a Rdio REST interface would be: You should disclaim that these URLs could just as well be * /rdio?q=1&s=63 * /rdio?q=1&s=63-8 * /rdio/4E7?q=1 * /rdio/4E63?q=1 and still be part of a RESTful API.
- swombat 16y ago
  No, those are not part of a REST API. You've got it wrong.
  - justincormack 16y ago
    Actually URLs are supposd to be opaque in rest so that is correct. Nice urls with http verbs but no hateos is what most "REST" APIs are though.
  - jamesbritt 16y ago
    Besides simply asserting the OP is wrong, perhaps you could explain what differences (aside from aesthetics) there are between /rdio/api/1/artist/1/tracks/2 and /rdio?api=1&artist=1&tracks=2 Routing code on the server can treat them as identical; is there anything about these two URL formats that would trip up a client? Does it change how caching might work?
    - nikcub 16y ago
      well I believe both are not correct. the idea is that you can build a generic 'REST' client and point it to almost anything that is a 'REST API' and it will work, in the same way we can now with web browsers a REST client will never figure out /api/1/ - which is why resources go in the path and query parameters go in as, well, query parameters :) from the server side you are right that modern front controllers and routing can make it all the same (heck, I can route resources to different subdomains, if I want), but a proxy does not know what the front controller logic is (ie. working backwards to what part is what).
      - masklinn 16y ago
        > the idea is that you can build a generic 'REST' client and point it to almost anything that is a 'REST API' and it will work, in the same way we can now with web browsers That's a stupid idea. REST is built on two things: content types and resource location. The content types indicate the meaning and location of the resources, if the client does not understand the content-type, it can not do anything. You can not "build a generic 'REST' client and point it to almost anything that is a 'REST API' and it will work", that makes no sense. Indeed, that's not what web browsers do: the driver of the API on a website is the user, not the browser. > a REST client will never figure out /api/1/ - which is why resources go in the path and query parameters go in as, well, query parameters :) That's completely irrelevant.
        nikcub 16y ago
        > That's a stupid idea. REST is built on two things: content types and resource location. here is what my generic REST client looks like: * HTTP[s] * JSON * Atom and RSS * Caching layer some controller login in between all of these. I inherit this to implement simple models and controllers in the client and just tell it which resources I want (like fields in a database) how is that not a generic client? for twitter I have classes called users and statuses, with each method defined. for google I have similar classes. this all took minutes for me to get working - I thought that was the entire point of REST? read the original desertion, sec. 5.2.2 connectors: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_2 http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch... > if the client does not understand the content-type, it can not do anything. generic doesn't mean understanding the payload, it means understanding the protocol
  - masklinn 16y ago
    Behold, the know-nothing. Sorry sir, I'm not wrong, those would be perfectly valid as part of a REST service, including as alternatives to tptacek's description. Readability of the URLs has nothing at all to do with RESTfullness. The only thing REST says about the data transmitted (the URL in this case) is that it's the container for the application's state, and most interpretations of this is that the URL is entirely opaque. And indeed, Fielding has suggested/explained this several times.
    - swombat 16y ago
      See http://en.wikipedia.org/wiki/Representational_State_Transfer http://en.wikipedia.org/wiki/Representational_State_Transfer Those are not REST because they are not resource-based. Correct REST: http://blah.com/widget/:id http://blah.com/widget/:id - GET, PUT, POST, DELETE How does that fit with your /rdio/4E7?q=1 ? Where's the resource? What is the id? What is q anyway? You can pass parameters with a ? in REST... for example, you might do GET http://blah.com/resource/123?format=xml http://blah.com/resource/123?format=xml But there's still a clearly identified resource which the GET is performed on. Sure, technically, by stretching things a bit, you could claim that /rdio?q=1&s=63-8 is a REST GET request for resource id "63-8". And, technically, you'd be right, much like technically, this is valid C: http://stackoverflow.com/questions/18642/what-is-the-most-unreadable-programming-language/18767#18767 http://stackoverflow.com/questions/18642/what-is-the-most-un... But just because it's valid doesn't mean it's in any way good. Those are horrible examples. So no, those URLs could not "just as well" be those nasty examples you give. They could, much more poorly, be those examples, and still be technically valid. By the same reasoning, "Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo" is just as good english as Shakespeare.
      - Darrel 16y ago
        All query string parameters are used to identify the resource also. RFC 3986 states "The query component contains non-hierarchical data that, along with data in the path component (Section 3.3), serves to identify a resource within the scope of the URI's scheme and naming authority (if any)." There is absolutely no difference between path segments and query parameters from the perspective of resource identification.
deleted 16y ago
[deleted]
nikcub 16y ago
I don't like API version numbers in the URI. It implies that a resource is different just because you are using a newer version of the API. My own most recent implementations use Accept: and Content-Type to define version compatibility, which is what content negotiation is supposed to be about. Versioning in the old web API sense meant changing the way the protocol works, and REST will always be REST and the resources will always be resources. All that is likely to change between 'API versions' is formats, which you negotiate with headers, and adding new fields, which old clients can either ask not to get through content negotiation or can safely ignore.
- Groxx 16y ago
  I can see it both ways. APIv2 is not the same resource as APIv1, so why send it to the same location? Similarly, APIv1/user/1 may very well not contain the same information as APIv2/user/1, so are they really the same resource? They likely refer to the same semantic resource, but if user/1 != user/1, they're not the same from a data standpoint, which is what APIs are generally used for.
  - nikcub 16y ago
    If version 1 of a resource is not a subset of version 2 of a resource, and they are not accessing the same record, then they should be separate resources what 'API' is signaling is what the client is capable of understanding, which is what content negotiation headers are for I think of it no different to the same resources for web browser consumption (for humans) - I don't place new designs of a website into /design1/ /design2/ etc.
    - jerf 16y ago
      Bear in mind the more things like "Well, you just have to properly use the content negotiation headers" you add to your API, the more the "simplicity" argument of REST goes out the window. I'm not sure I've ever seen really correct use of the content-negotiation headers and claiming it's a solution is dubious... sort of like how I'm still waiting to see proper use of XML Namespaces in the wild. They seem relatively simple to me but the evidence suggests strongly otherwise. That doesn't make REST "bad", but I think it does start to make the quasi-religious aspect of it less obviously correct.

pkulak 16y ago

I agree. I recently built an API for a project of mine and I decided to make it REST-like, but not use the HTTP method to distinguish actions. In some circumstances you can only use one (JSONP, for example), so I sacrificed some purity for "the real world". This seems like it goes a bit over the line, however.