In REST, How to discover acceptable media types?

Question

Given a REST api. I want to learn what media types I can set in the Accept header. How should I this?

I know I could do a random

GET http://some.api.com/
Accept:flying/elephants

and hope for a 406 with a body that has the correct acceptable media types.

Is there a better way?

Answer 1

In theory, API could indicate supported Content Types via HTTP OPTIONS

Usually, API offers either

1. Documentation
2. Specific resource of supported Accept-header values.

Also (as you might know), Accept-header values are usually bound to IANA defined MIME types

Answer 2

One issue with this is any URI within the API can respond with different media types. It's very common to have different endpoints in the API return different content types.

You could use multiple wildcard requests to probe for support.

You can start with Accept: */* and then application/* text/* */json */xml etc. You would receive a non-exhaustive list, but you'd get the big ones and the the preferred ones.

There's other weird edge cases. For example OData allows you to specify a $format parameter in the URL to define the response type. This overrides the accept header. Thus every format is it's own URI.

It'd be cool if APIs made more use of the alternate link relationship (http://www.w3.org/TR/html5/links.html#rel-alternate), i think that would be the most appropriate. That combined with the type attribute of the link would let you know all the formats for any resource you retrieve. Again it would be specific to each URI though.