Json-api: JSON API content type makes exploring in the browser impossible

[masterspambot]

I would like to target the problem that was introduced in our Kathatrsis library by @Ramblurr:

https://github.com/katharsis-project/katharsis-core/issues/310

Since JSON API uses a custom content type, and Katharsis correctly sets this, the result 
is you can't just view a Katharsis api response in the browser. 

On firefox at least, it prompts you to download the response body.

Perhaps setting Content-Disposition to inline would work?
Has anyone seen this before? What's the workaround?

Do you think that standard should be extended/updated to face the following problem?

[Ramblurr]

After some testing it appears Firefox and Safari are the only ones that download the response. Chrome and Opera display it as text.

[ethanresnick]

On my Mac, with the latest Firefox (46.0.1) and Safari (9.1 aka 11601.5.17.1), I'm having trouble reproducing this behavior. That is, both standard application/json and application/vnd.api+json files render in the browser without prompting a download. I do vaguely recall seeing the behavior you're describing in an older version of Safari, and it's possible the Windows version of Firefox has this issue too.

Regardless, I'm not sure there's anything JSON API can do here. I'd try using Content-Disposition, as you suggested and, if that doesn't work, opening issues on the browsers' bug trackers asking them to treat +json content types the same way they treat application/json (which is a good thing for browsers to do anyway, and not just for JSON API).

[jamesplease]

I was able to reproduce this in the latest Safari with the latest macOS.

Safari: Version 10.0.3 (12602.4.8)
macOS: Version 10.12.3 (16D32)

Content-type header:

Content-Type:application/vnd.api+json

Adding in Content-Disposition did not help, but switching to application/json did. It's not ideal, but to get around it I'm switching my API to using good ol' application/json.

[tkellen]

There is a subtle distinction here that probably could use a non-normative annotation.

From the spec:

Servers MUST send all JSON API data in response documents with the header Content-Type: application/vnd.api+json without any media type parameters.

You may read this as "I can only send application/vnd.api+json". That is wrong. There is nothing here limiting you from sending "non-JSON API data". Once you do that, you can do whatever the heck you want.

As an example, if a client indicates that it accepts text/html (read: all browsers), your server could (and ideally would) render a totally different representation that is useful for the context of a browser. Use html, use links, use tables, use whatever you want. Make it a website. Don't ship a sea of JSON to a human client. JSON is horrible for human consumption.

If you only ship application/vnd.api+json you are missing a lot of the value of content-type negotiation.

[tkellen]

I would gladly review and lead our team in landing a PR that non-normatively adds something to this effect to the specification.

[ethanresnick]

FYI, I opened https://bugzilla.mozilla.org/show_bug.cgi?id=1410587 to hopefully get this fixed in Firefox

Edit: The firefox bug has now been fixed, and will land in FF 58: https://bugzilla.mozilla.org/show_bug.cgi?id=1388335