Looking at using the http Accept header to branch if the server should return html or json of a resource. I was thinking of just using:
Accept: application/json
But further research and reading the GitHub API, the standard seems to be:
Accept: application/vnd.company.app+json
What is the advantage of doing this? Why not just use application/json without the vendor prefix of company and app?
The major difference is that application/json is a generic definition. Just because a request document is formatted as "application/json" doesn't mean that it could still be consumed by your application.
For the most part, on the server side you'd find yourself registering your media-type as being provided by your generic serialisation/deserialisation library (e.g. Jackson), so there's very little practical difference which it makes - if the provided document is not deserialisable to the the class you're expecting then there'll be an exception which will duly get turned into a 40x response code.
However, it's useful to be sure that both your server and your client expect to be speaking the same language. That can be logged and it can help to locate problems, either from external clients who expect an 'old' version of the API or from internal issues relating to incompatible client-server combinations.
