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?

Gnosticism

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.

Torbert

Thanks for the response. I'll have to look into using parameters. Is it ok to use them as the "type" attribute of a link. eg: <link href="someurl" method="post" rel="does_something" type="application/xml; schema=person-v1" /> to denote that if you post xml that follows the person-v1 schema to someurl, it will do something. – Gnosticism

@bhazzard, yeah, I would think so. – Torbert

You could also use a custom HTTP header. See #3561881 – Manure

HTTP spec says one thing, Roy Fielding says another, quoting: "A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state (...) Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types)." from: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven – Deckle

Another option to let the client know how to handle data related to your application specific RDF description and use and RDF aware MIME type. For example by JSON it can be JSON-LD, by XML it can be RDF/XML. – Selector

Answer 2

I have seen a couple of frameworks and tutorials that recommend vendor specific mime-type to "solve" issues with making your REST interface "truly RESTful" simply because it can be done and somehow that makes it kosher for a REST service.

One issue with this approach is that by its nature is a hack or cheat to "make it work" the way you want when the whole point of shifting to a hypermedia-driven REST service is to change the model of your API and service and change how you approach the problem. Sneaking a "valid" or allowed but not recommended HTTP value for the Content-Type is like telling the starving Venezuelans that rats are fish so they could eat them without sin during Lent. Is there anything wrong with eating a rat if that's all you have? Probably not. But does pretending its a fish make it a fish? Of course not. If you need an interface that's contract driven, use RPC or SOAP or even a custom vendor mime-type. But don't point to the spec and say it's Rest, because in the end your eating a rat and everyone knows it and you're only lying to yourself.

The second issue is that you are losing the actual rewards of the hypermedia-driven interface when you cut corners. Right away you have run into issues with user agents and your own server having to jump through hoops or simply give up because the mime-type was unfamiliar. All because you thought you could have it both ways when the point isn't to impress your clients with claims of a true Rest service or to lighten the load a bit by shedding the (obviously valuable for some contexts) extra weight of a contract-driven interaction, it was to change how your service actually interacted with external clients.

Finally, I'm really unclear on how a vendor specific mime-type actually enforces a contract any better than a defined endpoint? All of the sites that mention this technique seem to just be glowing with relief that this option exists and, quite frankly, a bit smug and pleased that they are using it, like they know it's technically "naughty" but it's just so easy and fixes everything. What does it fix? In your case, why wouldn't you simply have your inbound person request/content go to:

POST /myRestService/people

and if they have some other request, have that go to a different endpoint intended for that other data type? If you need a method does_something, wouldn't you either go with:

GET /myRestService/people/personID_123/does_something 

or

GET /myRestService/people/does_something/personID_123

depending on the exact context?

And just so I don't sound mean on top of loony, any frustration or anger is not at all directed at you or your question, but at the "solution" of the vendor mime-type and the obsession everyone has developed for the "Roy Fielding officially-approved and stamped as valid REST service" that apparently no one is even able to provide a working public example of, leaving only a sense of urgency to adopt it right away taking whatever shortcuts needed and we can deal with the shame and finger pointing later when we actually fix the problems the shortcuts made.

Galosh