4 ms·
> Should the media type change based on Accept headers or based on the URL? To ensure browser explorability, it should be in the URL. The most sensible option h
by teddyh 7y ago
> Should the media type change based on Accept headers or based on the URL? To ensure browser explorability, it should be in the URL. The most sensible option here would be to append a .json or .xml extension to the endpoint URL.
I disagree with this. The most elegant solution is to use Accept headers, and you should therefore implement that. Of course, since those are hard to use from a browser, you should also solve that problem, but solve that problem separately. I usually do that by supporting an extra ?type=application/json query parameter, which internally the server-side code converts to an Accept header, which is then interpreted normally. Note that I use the media type, not a possibly ambigous “.json” extension. Would “/foo.json” mean that the data is of type application/vnd.hal+json or maybe application/vnd.api+json? Who knows?
IMO, file name extensions do not belong in URLs. URLs were never meant to be files, and we should try to avoid .html, .cgi and .php in our URLs. See also Cool URIs don't change from 1998: https://www.w3.org/Provider/Style/URI https://www.w3.org/Provider/Style/URI
- wwweston 7y agoUsing Accept headers is the right thing, for the reasons you specify, and also the additional reason that they allow for the client to specify a list of possibilities that can be negotiated down to a result (server doesn't understand `application/vnd.hal+json`? maybe it can still send you `application/json`). That said: the extension-implies-media-type approach may not be right for an application server that renders a resource on the fly, but it does seem to have a place in the specific kind filetree-via-http web server, where the resource specified by a given URL is already rendered to a specific media type, and the server really only has two choices for figuring out what that type is: parse the file (potentially expensive) or apply a heuristic set up in the server configuration to the filename (potentially not specific enough or outright wrong). Neither choice is necessarily wrong for that subcase. I'm iffier on saying as much for media-type-in-query-string method. It's easy enough to use a client built for sending headers like Postman or curl or to augment common browsers with extensions that using the understood HTTP convention seems like the right thing for most cases. The only exceptions I can think of would be those where debugging a media type specific issue needs to happen on machines devs don't control. Needing to debug issues on machines devs don't control is common enough, but issues specific to rendering one media type should be rarer, and the intersection of both of them should be vanishing unless something isn't right elsewhere in the dev process.
- Bombthecat 7y agoAlso, rest is interesting because it solves a lot of "base protocol" questions. Accept header is part of standard http. So that should be the default way.
- Supermancho 7y agoThat isnt a problem. Your API docs are the solution. Mapping communication protocols on to your applicarion for zero benefit over any other strategy. Yhis idea has been a hindrance at various cargo cult teams for decades. At least the RFC doesnt try to fool others into the fantasy.
- PretzelFisch 7y agoI don't agree that there should be browser explorability. I don't understand why that would even be a concern. When I explore it's from documentation, postman or curl. The browser is kind of horrible for this why support it at all?
- detaro 7y agoIf "browser explorability" is important, this article fails to discuss it properly when it comes to authentication, too.