2

We are developing a REST API that can return a zip file. The content of the zip file can be in CSV or EXCEL format. How should the Accept header describe the two scenarios?

Accept=application/zip;format=csv
Accept=application/zip;format=excel

Is the example above valid?

According to RFC7231 "Media ranges can be overridden by more specific media ranges or specific media types. If more than one media range applies to a given type, the most specific reference has precedence." https://www.rfc-editor.org/rfc/rfc7231#section-5.3.2

Community
  • 1
  • 1
TXdev
  • 85
  • 11
  • Looks like a valid use of media type parameter, but I'm wondering 1) if it couldn't be better named (e.g. content rather than format, which you'd expect would describe the format of the zip file, maybe its encryption level or something else) 2) if there wouldn't be a more simple way to convey this information (in particular the RFC mentions that media type parameters are rarely used) – Aaron Nov 04 '19 at 10:56
  • Thank your for the input. 1) Yes we should use content. 2) We would like to have the information in one place. Any other suggestions? Perhaps add a content query param or another header? – TXdev Nov 04 '19 at 11:40
  • Headers are somewhat obscure/not the first thing you look at, and media type parameters even more, I feel like either a query param or an additional path fragment would be more explicit than using an http header and would help with maintainability. – Aaron Nov 04 '19 at 11:53
  • media type parameters like charset are not rarely used. Do you have a RFC source to your argument? Seems to me that the parameters are there for scenarios like the one described. – TXdev Nov 04 '19 at 12:25
  • charset is often used yes, but that's about the only one. The RFC you've linked uses "the rare usage of any media type parameters in Accept" as an argument when discussing the historical use of "q" as a separator. – Aaron Nov 04 '19 at 12:31
  • Note that your intended use if perfectly valid and relevant, I'm just worrying about an hypothetical guy being passed your application's maintenance with lackluster documentation in 5 years. He'll probably notice the extra path fragment or query parameter faster than a media type parameter. – Aaron Nov 04 '19 at 12:34
  • Also charset is a special case (defined in 3.1.1.2), and for requests it's best to use Accept-Charset than an Accept with charset as a media type parameter. It's in Content-Type that it's very common as a way to tell the client how to decode the data it's receiving. – Aaron Nov 04 '19 at 12:45

0 Answers0