w3c/Micropub

Custom MIME type for error and configuration response

Closed this issue · 6 comments

cweiske commented

Instead of returning a generic Content-Type of application/json, both error response and configuration response should use a custom MIME type, for example text/micropub-error+json and text/micropub-configuration+json.

Clients may validate the returned JSON against a schema when they get a specific content type.
They can also see that the server sends the correct data, and not just some standard error garbage that's not readable by clients expecting a specific data format.

Using custom MIME types is also suggested by http://jsonapi.org/format/#content-negotiation-servers

voxpelli commented

Why? This seems like a fairly uncommon way for a content-type on an error message? Why not just use the plain json content type?

cweiske commented

I've had enough API situations in which validating the returned content type quickly told me that either I made an error, or the API sent something strange to my request. reduced debugging time.

voxpelli commented

For the record: In all of the API situations I've been I would find this to be unexpected and something that would possibly increase debugging time instead. So unless I'm -1 unless it can be shown that this is a typical established pattern for API:s like this, which I consider it not to be.

(Would also want to know how it would work with Accept headers, mime type registrations etc)

aaronpk commented

I agree this seems needlessly complicated. There's also a pretty big difference between Micropub and the JSONAPI standard, so I don't think that makes a good example to draw from. Are there other examples of RPC style APIs making up their own mime types?

aaronpk commented

We discussed this during the f2f discussion. Here are our results.

  • Using profile in the content type is a better way to indicate the specific flavor of JSON, since creating new content types involves a lot of overhead. This would look something like:
Content-type: application/json; charset=utf-8; profile="https://www.w3.org/ns/micropub.json"
  • We won't make any changes for this version, sticking with application/json. In consideration for future versions, especially if there are incompatible changes, adding a profile to the content type would help. At that point, we can add a profile according to whatever conventions are established in the future. More notes on using profile.

Please close this issue if you feel like it has been addressed.

csarven commented

Apparently there is an RFC for Problem Details for HTTP APIs and

The data model for problem details is a JSON [RFC7159] object; when
formatted as a JSON document, it uses the "application/problem+json"
media type.

  • 👍2