Hacker News Reader

Comment by di | Hacker News Reader

Github also versions their API via headers, but uses the `Accept` header instead: https://developer.github.com/v3/media/

View on HN

I consider this a misuse of the Accept header. They're defining a bunch of custom media types, which in of itself is pretty weird, but then they're not actually using those media types as the Content-Type of the response. So I can send a request where I say 'Accept: application/vnd.github.full+json', but the response I get back is 'Content-Type: application/json; charset=utf-8', which means the server intentionally handed me a media type that I explicitly said I didn't accept.

I don't understand why they didn't just use the X-GitHub-Media-Type header as a request header.

>They're defining a bunch of custom media types, which in of itself is pretty weird,

No it isn't. If you're doing REST and your resources are not completely trivial (arguably, even if they are) you should be defining a custom media type for them (think HTML5).

>but then they're not actually using those media types as the Content-Type of the response.

Ok, that is very weird.

I disagree, if the response body is a valid application/vnd.github.full+json document, then they sent you what you asked for, they just labeled it differently (but still correctly).

Nothing in the spec says the Accept and Content-Type must match.

The spec may not mandate that Accept and Content-Type match, but it's still pretty strange. The client is saying "I accept this particular vendor-defined format, with an underlying structure of JSON" and the server says "ok here's a blob of JSON". Nothing in the server's response indicates that the response actually belongs to the specific vendor-defined media type, it could be handing back arbitrary JSON.

I get that from a practical standpoint the server needs to send back a JSON Content-Type, otherwise a lot of clients won't understand that it's JSON and won't decode it properly. But given this, shouldn't they have picked a different header to declare the API version?

What's the benefit of using the Accept header in this fashion? AFAICT there is no benefit at all over just using a custom header.

I'm surprised they don't run into CDN issues.

Have run into more than one issue with the vary: Accept being ignored, resulting in everyone getting the result from the first man in regardless of header variance.

Especially noticeable when we tried supporting both JSON and XML via the accepts header, with the version in the mime.

I don't think they run their API servers behind a CDN, that's not really a common thing at all.

Reply on news.ycombinator.com