Hacker News Reader

Comment by icebraining | Hacker News Reader

    The good

    GitHub uses custom MIME types for all of their responses. They're using the vendor extensions that I talked about in my post, too. For example:

        application/vnd.github-issue.text+json

    Super cool.

Hmm, I wouldn't call that "good." It's definitively better than sending 'application/json' or 'application/xml', which tell us nothing about the structure of the data, and it's probably inevitable in their context, but "good" would be to use an actual standard mimetype instead.

The problem with using mimetypes tied to the service is that it undermines the concept of Uniform Interface, by forcing developers to write clients specifically for that service. Imagine if instead of standardizing on (X)HTML, CSS, JS and a couple of image formats, each website used their own format.

View on HN

> but "good" would be to use an actual standard mimetype instead.

That only works if there is a standard mimetype correctly mapping to the needs of the platform. If you're writing a calendaring application you have one, but that's about it.

> The problem with using mimetypes tied to the service is that it undermines the concept of Uniform Interface, by forcing developers to write clients specifically for that service.

Uh... developers have to write clients specifically for that service unless there is a standard content type which the service can provide. Which happens almost never.

> Imagine if instead of standardizing on (X)HTML, CSS, JS and a couple of image formats, each website used their own format.

Does not follow. APIs and websites have a big difference: one is browsed by a human being, the other one is not.

>That only works if there is a standard mimetype correctly mapping to the needs of the platform. If you're writing a calendaring application you have one, but that's about it.

Standards don't fall from the sky, someone has to write and publish them. An "Issue" format is pretty much usable by any bug tracking software out there - Bugzilla, Redmine, etc. Github could perfectly have talked to them and define some common ground.

Is it their obligation? Of course not. But that would've been a "good" solution. This is just OK.

>Uh... developers have to write clients specifically for that service unless there is a standard content type which the service can provide. Which happens almost never.

See above. Usually it doesn't happen because providers don't make the effort.

Creating a generic standard is A LOT more work than creating an API for a specific application. Orders of magnitude more work.

Just to be clear: I'm not criticizing Github for using a custom format. It's obviously the what makes more sense for their business.

But in terms of a REST API, the proper solution would be to use a standard format.

There are 3 ways to use media types in web APIs. http://blog.kevburnsjr.com/domain-specific-media-types-and-r...

  0 domain specific media types    (application/json)
  1 domain specific media type     (application/vnd.github+json)
  many domain specific media types (application/vnd.github-issue.text+json, ...)

GitHub's v3 API uses the latter.

That is actually an interesting point. I can't pull up the HTTP spec or Dr. Fielding's dissertation right now, but what precisely is the mimetype supposed to signify?

It seems that that the encoding of the response (html/xml/json/etc) is being conflated with a content specification for the response. XML already allows you declare a schema for validation purposes. There have been a few attempts to standardize this on the JSON side, but that will never be a first-class citizen in JSON (nor do I think they should be).

It appears to me, if you really care about the content of your resource, then you should use the schema facilities provided by your encoding, rather than imposing it universally on the architecture side, as the article implies.

Historically, mimetypes (afaik) have never made any assumptions about the content of a resource, other than it adheres structurally to whatever the mimetype declares. Should be kept that way.

That limits the number of XML representations of any given resource to one, which can be a problem. In the context of a geographical object, XML might mean a KML file or an SVG image of the location, for example.

There are plenty of IANA approved mimetypes which define a schema - in fact, HTML itself provides plenty of semantic information about the data.

You could narrow it down using standard mimetypes even if the alternate representation is a xml derivative. application/svg or whatever the mimetype for that is. The encoding for svg is well defined; SVG tags merely lend structure to the content. The same goes for HTML and any other markup.

I'm undecided now though.

It's a slippery slope with custom representations. With generic XML or JSON, you still need a priori knowledge of the content to parse the reprentation manually. Then the benefit of a nonstandard mimetype is simply to be absolutely explicit about your content. Whether that should be canonical, I'm not sure.

> what precisely is the mimetype supposed to signify?

The meaning of the document you're returning.

> XML already allows you declare a schema for validation purposes.

But XML does not let you tag documents with arbitrary schemas. As far as I know, there is no way to include a RelaxNG or Schematron schema reference in an XML document in a standardized manner. Using specialized vendor mime types lets you provide this information: the mime type maps onto (among other things) the schema for the meta-type.

> It appears to me, if you really care about the content of your resource, then you should use the schema facilities provided by your encoding

There is nothing saying they can't go hand in hand. Indeed, it's quite the opposite: the vendor mime type you get maps directly to a corresponding schema for validation (the client generally should not validate what it gets, really, though it can).

> Historically, mimetypes (afaik) have never made any assumptions about the content of a resource, other than it adheres structurally to whatever the mimetype declares.

That's very much incorrect. See: application/xhtml+xml, application/svg+xml, model/x3d+vrml, application/soap+xml. And on the vendor-specific side of things, application/vnd.google-earth.kml+xml.

Yes but HTML/CSS are general purpose formats. What can be standardized between the wide variety of web APIs out there?

All of these popular services can be expressed in standard ones like HTML/JSON.

Except as far as an automated tool is concerned, knowing that something is "HTML" or "JSON" is useless: it will not be able to consume it. So it's not a useful information for an API. Instead, specifying the precise subset of the general-purpose format (essentially the language, where the general-purpose format is a meta-language) helps just about everybody.

And that's what github does: the `+json` postfix indicates that they're returning a JSON dialect, the `vnd.github-issue.text` explains what that dialect precisely is.

I'm not saying that there should be "one format to rule them all" or that in many cases, having a custom format isn't inevitable, but there are a lot of standard formats that can be reused. And you can use a mix of standard and custom formats for different resources.

In this case, I think the best solution would be to develop a standard "issue format" that would be used by all bug trackers, instead of each having its own. In another example, the "Users" part of the API could very well reuse one of the existing formats.

This also circles back to a (controversial) opinion I have, which is that JSON isn't the best solution for most of these services. With all of its flaws, XML has features like namespaces which enable a better reuse of standard formats - in the "Issues" example, where there is a "user" key, an XML document could integrate a foaf:Person element which is standardized.

Reply on news.ycombinator.com