7 ms·

The last case sounds like user error to me. You could say the same for using Accept headers - what happens if the user tells their line-drawing client to reques

The last case sounds like user error to me. You could say the same for using Accept headers - what happens if the user tells their line-drawing client to request a spreadsheet?

stingraycharles 9y ago
In the case of accept headers, you would have actual negotiation; the client sends all of the formats it accepts, and the server chooses the most suitable one. If none are available, it would return a 406 Not Acceptable. The problem with putting another, incompatible serialisation format on top of that is that it creates conflicts, and inherently requires one to reinvent the wheel, or have a less flexible solution. I simply fail to see what problem it solves.
- eponeponepon 9y ago
  That's a fair response, but you're presupposing a client that behaves as it's supposed to. To my mind, the problem it solves is familiarity - average users are accustomed to "file.html", not "file(oh hey, send the text/html version please)". All of this is heavily influenced by who your users actually are, of course.
- rimliu 9y ago
  > the client sends all of the formats it accepts And currently many clients only support JSON. As do many backend systems.
- PeterisP 9y ago
  In practical applications, I'd want it to be the opposite way around - the server will be coded to support multiple formats since it serves many clients and many types of clients, but any particular client explicitly targeting that server will likely implement just a single format for exchanging data with your app. So you'd want the server to send all the formats it can provide (i.e. as a list of different resource URLs) and the client chooses whatever it prefers, entirely the other way around as you describe. Furthermore, server being able to dynamically respond "I don't do your preferred format" is not a desirable outcome; from the client perspective you'd want to know if the format is available right away, and for a whole class of URLs, not an individual URL at the very last moment. I.e., I'd want it to be equivalent to a "compile time check", that an URL scheme promises that the server will always be able to return type X for such URLs, instead of a "runtime check" where the availability of a particular format is known only after you try it.
  - stingraycharles 9y ago
    > So you'd want the server to send all the formats it can provide (i.e. as a list of different resource URLs) and the client chooses whatever it prefers, entirely the other way around as you describe. What is the advantage of that, compared to having normal Accept: encoding ? Please note that in the negotiation phase, a server uses the format that the client actually prefers; it's able to tell the server these things (e.g. "if you have json, give me that, otherwise I'll take XML). Your solution requires an additional round-trip for this same negotiation.
- jmull 9y ago
  It doesn't have to be done in a bad/incompatible/new way. Here's what I did for an API I worked on recently supports JSON and XML: The general route for a resource is an endpoint that can serve both application/json and application/xml, the ".json" route identifies an endpoint that will serve only application/json and ".xml" identifies an endpoint that will serve application/xml. None of that conflicts with normal content negotiation, and normal conflict resolution is used. So if the client were to send a request to a .json endpoint with Accept: application/xml it would get a 406 response. The problem it solves is to make it straight forward to send ad hoc API requests from a browser but still control the format. The browsers I work with don't generally make it easy to specify an accept header. This is useful for demos, issue investigations, and ad hoc testing.
  - stingraycharles 9y ago
    > The problem it solves is to make it straight forward to send ad hoc API requests from a browser but still control the format. The browsers I work with don't generally make it easy to specify an accept header. This is useful for demos, issue investigations, and ad hoc testing. First of all, these things are supported by HTTP headers; you can send "Accept: application/json;q=0.9, application/xml;q=0.1" and the server will always send JSON if it supports it. The problem you mention is fair, but REST APIs are designed for consumption by computers, not humans. So while it is a fair point, it is explicitly a non-goal for REST APIs.
    - jmull 9y ago
      On your second paragraph... I don't think you can generally state that REST APIs don't need to be developable, supportable, teachable/learnable. Ad hoc requests support these things in useful ways that scripted requests do not. That makes it a fair goal for REST APIs. On your first paragraph, sorry I don't understand your point. I showed how this can be done in a way that is fully consistent with standard content negotiation, like your example.

The last case sounds like user error to me. You could say the same for using Accept headers - what happens if the user tells their line-drawing client to request a spreadsheet?

stingraycharles 9y ago

In the case of accept headers, you would have actual negotiation; the client sends all of the formats it accepts, and the server chooses the most suitable one. If none are available, it would return a 406 Not Acceptable. The problem with putting another, incompatible serialisation format on top of that is that it creates conflicts, and inherently requires one to reinvent the wheel, or have a less flexible solution. I simply fail to see what problem it solves.

eponeponepon 9y ago
That's a fair response, but you're presupposing a client that behaves as it's supposed to. To my mind, the problem it solves is familiarity - average users are accustomed to "file.html", not "file(oh hey, send the text/html version please)". All of this is heavily influenced by who your users actually are, of course.
rimliu 9y ago
> the client sends all of the formats it accepts And currently many clients only support JSON. As do many backend systems.
PeterisP 9y ago
In practical applications, I'd want it to be the opposite way around - the server will be coded to support multiple formats since it serves many clients and many types of clients, but any particular client explicitly targeting that server will likely implement just a single format for exchanging data with your app. So you'd want the server to send all the formats it can provide (i.e. as a list of different resource URLs) and the client chooses whatever it prefers, entirely the other way around as you describe. Furthermore, server being able to dynamically respond "I don't do your preferred format" is not a desirable outcome; from the client perspective you'd want to know if the format is available right away, and for a whole class of URLs, not an individual URL at the very last moment. I.e., I'd want it to be equivalent to a "compile time check", that an URL scheme promises that the server will always be able to return type X for such URLs, instead of a "runtime check" where the availability of a particular format is known only after you try it.
- stingraycharles 9y ago
  > So you'd want the server to send all the formats it can provide (i.e. as a list of different resource URLs) and the client chooses whatever it prefers, entirely the other way around as you describe. What is the advantage of that, compared to having normal Accept: encoding ? Please note that in the negotiation phase, a server uses the format that the client actually prefers; it's able to tell the server these things (e.g. "if you have json, give me that, otherwise I'll take XML). Your solution requires an additional round-trip for this same negotiation.
jmull 9y ago
It doesn't have to be done in a bad/incompatible/new way. Here's what I did for an API I worked on recently supports JSON and XML: The general route for a resource is an endpoint that can serve both application/json and application/xml, the ".json" route identifies an endpoint that will serve only application/json and ".xml" identifies an endpoint that will serve application/xml. None of that conflicts with normal content negotiation, and normal conflict resolution is used. So if the client were to send a request to a .json endpoint with Accept: application/xml it would get a 406 response. The problem it solves is to make it straight forward to send ad hoc API requests from a browser but still control the format. The browsers I work with don't generally make it easy to specify an accept header. This is useful for demos, issue investigations, and ad hoc testing.
- stingraycharles 9y ago
  > The problem it solves is to make it straight forward to send ad hoc API requests from a browser but still control the format. The browsers I work with don't generally make it easy to specify an accept header. This is useful for demos, issue investigations, and ad hoc testing. First of all, these things are supported by HTTP headers; you can send "Accept: application/json;q=0.9, application/xml;q=0.1" and the server will always send JSON if it supports it. The problem you mention is fair, but REST APIs are designed for consumption by computers, not humans. So while it is a fair point, it is explicitly a non-goal for REST APIs.
  - jmull 9y ago
    On your second paragraph... I don't think you can generally state that REST APIs don't need to be developable, supportable, teachable/learnable. Ad hoc requests support these things in useful ways that scripted requests do not. That makes it a fair goal for REST APIs. On your first paragraph, sorry I don't understand your point. I showed how this can be done in a way that is fully consistent with standard content negotiation, like your example.