4 ms·

I would disagree on the artificial file endings. It's a very transparent way to allow the client to request a resource with a specific content type, visible rig

I would disagree on the artificial file endings. It's a very transparent way to allow the client to request a resource with a specific content type, visible right there in the URI. After all the .json and .xml are unique representations of the same resource and can reasonably have their own URI

eponeponepon 9y ago
Yeah, there aren't many situations where that really washes - it's a reasonable rule to have in mind when designing your API, but it seems to clash with the principle of designing "for your clients, not your data". Your clients are often using a browser and don't get to pick the content-type they request. I guess you could contrive to have /resources/xml/apples and resources/json/apples serve the same content, but otherwise it's query strings or interposing a 'choose a representation for your content' page. Naturally, none of this is a problem if your clients are not humans, I suppose.
hdhzy 9y ago
The thing is that resource should have ideally one URI and selecting representation should be done through content negotiation (e.g. Accept header). Of course having an option to use file extensions makes debugging easier in a browser.
- jmull 9y ago
  I don't mean to pick on you at all, and I hope this doesn't come off that way... but this is a very interesting statement. You start off with a statement of ideals which you then directly contradict with a real, practical concern. I think that has to mean the ideal isn't a good one and in fact -- here's the interesting part, IMO -- one or more of the considerations on which the ideal was based are also invalid. Personally, I think the "lesson" here is that we should not aspire to have a one-to-one relationship between URI and resource. The attraction is that it's simple. But I think it's clearly too simple; that is, it is too inflexible to be useful: resources cannot be transferred between hosts or shared by multiple hosts; resources can only be organized in a single fixed way (for all time!) within a service (itself with a fixed organization within its host). It seems better not to try to impose these restrictions on resource identity and instead separate how a resource is identified from how it is retrieved. E.g. use a UUID to unambiguously identify a resource across all space and time, but retrieve the resource using a set of URLs which can change over time. I mean, the idea that a resource can move (its URL has changed) has been is built into HTTP for decades. Why attempt to create a service that assumes this does not happen?
stingraycharles 9y ago
A URI should represent a resource, regardless of its serialisation format. Serialisation really is part of the HTTP headers, and the support in there is great. Using this allows the web browser and the web server to completely negotiate an acceptable format themselves. Adding the serialisation format to the URI also creates a conflict: what would happen if you request a .json, but the web browser doesn't accept this format ?
- eponeponepon 9y ago
  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.
    - 9y ago
kuon 9y ago
I agree. Also it might be more convenient when doing get request. Imagine an API generating images like /cat/300x300.jpg the ability to switch to .png is really handy. Of course you could do /cat/300x300/png and don't use extensions. I think it's up to particular use cases.

eponeponepon 9y ago

Yeah, there aren't many situations where that really washes - it's a reasonable rule to have in mind when designing your API, but it seems to clash with the principle of designing "for your clients, not your data". Your clients are often using a browser and don't get to pick the content-type they request. I guess you could contrive to have /resources/xml/apples and resources/json/apples serve the same content, but otherwise it's query strings or interposing a 'choose a representation for your content' page. Naturally, none of this is a problem if your clients are not humans, I suppose.

hdhzy 9y ago

The thing is that resource should have ideally one URI and selecting representation should be done through content negotiation (e.g. Accept header). Of course having an option to use file extensions makes debugging easier in a browser.

jmull 9y ago
I don't mean to pick on you at all, and I hope this doesn't come off that way... but this is a very interesting statement. You start off with a statement of ideals which you then directly contradict with a real, practical concern. I think that has to mean the ideal isn't a good one and in fact -- here's the interesting part, IMO -- one or more of the considerations on which the ideal was based are also invalid. Personally, I think the "lesson" here is that we should not aspire to have a one-to-one relationship between URI and resource. The attraction is that it's simple. But I think it's clearly too simple; that is, it is too inflexible to be useful: resources cannot be transferred between hosts or shared by multiple hosts; resources can only be organized in a single fixed way (for all time!) within a service (itself with a fixed organization within its host). It seems better not to try to impose these restrictions on resource identity and instead separate how a resource is identified from how it is retrieved. E.g. use a UUID to unambiguously identify a resource across all space and time, but retrieve the resource using a set of URLs which can change over time. I mean, the idea that a resource can move (its URL has changed) has been is built into HTTP for decades. Why attempt to create a service that assumes this does not happen?

stingraycharles 9y ago

A URI should represent a resource, regardless of its serialisation format. Serialisation really is part of the HTTP headers, and the support in there is great. Using this allows the web browser and the web server to completely negotiate an acceptable format themselves. Adding the serialisation format to the URI also creates a conflict: what would happen if you request a .json, but the web browser doesn't accept this format ?

eponeponepon 9y ago
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.
  - 9y ago

kuon 9y ago

I agree. Also it might be more convenient when doing get request. Imagine an API generating images like /cat/300x300.jpg the ability to switch to .png is really handy. Of course you could do /cat/300x300/png and don't use extensions. I think it's up to particular use cases.