How can I use vendor specific MIME-TYPES for a "private-labeled" REST API

Question

I'm developing a RESTful API. Currently I'm considering the use of resource-specific vendor MIME-types to convey semantics and meaning as well as well as serve as the "contract" between client and server.

So for example application/vnd.mycompany.person+xml would mean that the data in question is xml that represents a person.

I have a requirement to make this API "private-labeled" meaning a reseller could in turn provide the API to his customer without his customer knowing that it is my company's service. The way this would work is that my company would host the main api at a sort of generic url, i.e www.example.com/api then my company would use a CNAME to point our domain name to that url, and our resellers could do the same.

Internally all resource links would be relative from the API root, and so would respect the actual url that is being used.

HOWEVER, I don't want to have to understand/support arbitrary vendor specific MIME-types, so what should the "mycompany" part of the example MIME-type above be?

Answer 1

The HTTP spec says:

Use of non-registered media types is discouraged.

I used to use “custom” media types in my platform, but it caused issues with user agents (browsers, cURL, wget, etc.) not recognizing the content.

You could try to get your custom media type registered, but (A) that takes a while; (B) it’d take a real long while before user-agents would recognize the type, if ever; (C) you’ve indicated that you don’t want the company name always present anyway.

As an alternative to “custom” media types, I recommend utilizing media type parameters instead; they’re a blessed way to add supplementary information about content to media types.

Using parameters, your media type could be application/xml; mycompany-schema=person or maybe just application/xml; schema=person.