4 ms·

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

by 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.
- Groxx 16y ago
  That's part of my reasoning. Setting proper headers is, yes, more proper... and something essentially nobody does, and many simple API libraries don't support without making using them massively more complicated than prefixing all the URLs with "api/2". It's a correctness vs usability debate. I'd love to go for correct, but it's extremely painful to enforce in your users in practice.
- enduser 16y ago
  Using content negotiation, I can--if the server supports it--take the same URI (e.g. http://www.jerf.org/ http://www.jerf.org/) and pass it to an image viewer to see your face, to my address book to fetch your contact info, etc. Anything else requires the client knowing how to mangle URIs (e.g. adding /avatar.jpg, /contact.vcf).
  - awj 16y ago
    What, realistically, is the difference between knowing how to mangle URIs vs. knowing what content types are available for negotiation?
  - wahnfrieden 16y ago
    @awj: if your API does HATEOAS properly, so that your responses inline URLs to other related resources (aiding discoverability of your API through hypertext), then the client can naively take the URLs given to it and cleanly apply Accept headers to them as appropriate.
  - jerf 16y ago
    I know what content negotiation is; I've never seen it done right. The theory is all beautiful but in practice content negotiation never seems to work right because you never get two people to agree very well on what things are. Another manifestation of the usual semantic classification problem. It has a dubious track record in X as well. X has been able to do content negotiation for decades for the clipboard but even now it's still spotty and buggy, and that's with everything actually running on the same system. It looks easy. Heck, it looks very easy. It isn't. I can't even tell you exactly why it isn't as easy as it looks (beyond the semantic thing I mentioned above), but the state of the world is pretty clear.
nikcub 16y ago
if you don't want to use content negotiation, then stuff it into query parameters - that is what most API's do (and most that support full content negotiation do anyway) eg.?v=1&format=xml but interesting to note is that why is encoding easy to do as part of content negotiation, yet everything else is hard? you never see ?e=UTF-8 or &c=gzip
- pzb 16y ago
  Many APIs simply specify that the encoding is constant (always UTF-8) so this is not an issue. And many HTTP libraries simply handle the content encoding transparently. The challenge is some HTTP library APIs commonly used for developing clients offer the following interface: - GET $URL If you are lucky, then it might also support POST and offer a second parameter for the request body. If are really lucky, there is a way to specify arbitrary methods, but this is fairly rare.
- wahnfrieden 16y ago
  I'm all in favor of supporting fallbacks for more limited clients. But query params are not a great idea since they can prevent caching from happening.
  - kevinstubbs 16y ago
    Add a random number to the end as a param to force no-caching.
    - wahnfrieden 16y ago
      My point was that it's not a good thing for requests for cacheable content, that might not be cached since you used a query param to access it. Some caches ignore requests with query params since "queries" are often not static.

by nikcub 16y ago

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.

Groxx 16y ago
That's part of my reasoning. Setting proper headers is, yes, more proper... and something essentially nobody does, and many simple API libraries don't support without making using them massively more complicated than prefixing all the URLs with "api/2". It's a correctness vs usability debate. I'd love to go for correct, but it's extremely painful to enforce in your users in practice.
enduser 16y ago
Using content negotiation, I can--if the server supports it--take the same URI (e.g. http://www.jerf.org/ http://www.jerf.org/) and pass it to an image viewer to see your face, to my address book to fetch your contact info, etc. Anything else requires the client knowing how to mangle URIs (e.g. adding /avatar.jpg, /contact.vcf).
- awj 16y ago
  What, realistically, is the difference between knowing how to mangle URIs vs. knowing what content types are available for negotiation?
- wahnfrieden 16y ago
  @awj: if your API does HATEOAS properly, so that your responses inline URLs to other related resources (aiding discoverability of your API through hypertext), then the client can naively take the URLs given to it and cleanly apply Accept headers to them as appropriate.
- jerf 16y ago
  I know what content negotiation is; I've never seen it done right. The theory is all beautiful but in practice content negotiation never seems to work right because you never get two people to agree very well on what things are. Another manifestation of the usual semantic classification problem. It has a dubious track record in X as well. X has been able to do content negotiation for decades for the clipboard but even now it's still spotty and buggy, and that's with everything actually running on the same system. It looks easy. Heck, it looks very easy. It isn't. I can't even tell you exactly why it isn't as easy as it looks (beyond the semantic thing I mentioned above), but the state of the world is pretty clear.

nikcub 16y ago

if you don't want to use content negotiation, then stuff it into query parameters - that is what most API's do (and most that support full content negotiation do anyway) eg.?v=1&format=xml but interesting to note is that why is encoding easy to do as part of content negotiation, yet everything else is hard? you never see ?e=UTF-8 or &c=gzip

pzb 16y ago
Many APIs simply specify that the encoding is constant (always UTF-8) so this is not an issue. And many HTTP libraries simply handle the content encoding transparently. The challenge is some HTTP library APIs commonly used for developing clients offer the following interface: - GET $URL If you are lucky, then it might also support POST and offer a second parameter for the request body. If are really lucky, there is a way to specify arbitrary methods, but this is fairly rare.
wahnfrieden 16y ago
I'm all in favor of supporting fallbacks for more limited clients. But query params are not a great idea since they can prevent caching from happening.
- kevinstubbs 16y ago
  Add a random number to the end as a param to force no-caching.
  - wahnfrieden 16y ago
    My point was that it's not a good thing for requests for cacheable content, that might not be cached since you used a query param to access it. Some caches ignore requests with query params since "queries" are often not static.