Single purpose media types and reusability

Published on June 24, 2014

The one great thing about twitter is that you quickly find out what you failed to explain clearly :-)  My efforts in advocating for single purpose media types failed to clarify that by single purpose, I am not suggesting that these media types should not be re-usable.  Let me try and explain.

My realization was triggered by @@inadarai 's tweet to me,

I'm going to take the liberty of assuming that this tweet was slightly tongue-in-cheek.  However, it did highlight to me the part of my explanation that I was missing.

It is a whacky world out there

For those who have better things to do than keep up with daily craziness in Silicon Valley, the significance of this image may not be immediately apparent.  A new start-up called Yo is making the news with an application that simply sends the message "Yo" to someone in your social network.  The joke of this tweeted image is that many people are likely to copy this idea and we will have many apps on our phone where each one will send just a single one word message.

My response to @@inadarei included these two tweets,

Although still not a particularly serious suggestion, the example is extremely illustrative.  By single purpose media types, I am not suggesting that each and every API should invent media types that are designed to solve just their specific problems.  It is critical to realize that media types should be targeted to solve a single generic problem that is faced by many APIs.  It is only by doing this can we achieve the level of re-usability and interoperability that make the web successful.

Generalize the problem

By generalizing our problem space to the notion of a "salutation" we can define a single hypothetical media type and name it application/salutation+json.

To satisfy the functional requirements of an application that simply displays a single word message to an end user, all we need is a payload that looks something like:

{
   "message" : "Yo"
}

This media type could then be delivered by any API that wishes to transmit a single word message.  Now that the message has been generalized, there is no need to have a different client for each API.  In the same way that RSS feeds allowed us to use one client application to consume blog posts from many different blogs, so our salutation media type enables just a single client application for all APIs that support the format.

But that was a dumb example

Let me provide a more realistic scenario.   For many years I've been building ERP systems and for the last 7 years I've been working on a building an ERP API that uses media types and link relations to communicate information to a desktop client application.  For a period of time, I considered inventing my own media types for Invoices, Sales orders, Customers, Purchase Orders, etc, etc.  However, I quickly realized that the overhead of creating written specifications for the 500 or so entities that were in our ERP product  would be a mammoth and very painful task.  I would also never likely see any re-use out of those media types.  It is highly unlikely that I could convince any other ERP vendor that they should re-use our Invoice format as it would likely contain many capabilities that were specific to our API, and I'm sure they would believe that their format is better!

Don't those standards already exist?

As an industry we have tried on numerous occasions to create universal standards for interchange of business documents.  (e.g Edifact, ANSI X12, UBL).  None of these efforts have come close to having the adoption like HTML has, despite having massive amounts of money poured into convincing people to adopt them.

The problem with these previous efforts is they tried to bite off a bigger problem than they could chew.  In order to manage the size of problem they were trying to address, they first invented a meta-format and then applied schemas to that format to produce consistent documents for each business scenario.  The result was horribly complicated, with a huge barrier to entry.  If you don't believe me, here is the list of fields used by a UBL invoice.

Be less ambitious

Now imagine a much simpler scenario for just invoicing information.  Imagine if we could agree on a simple read-only format containing invoice information.  If services like Amazon, NewEgg, Staples, Zappos, etc, could expose their invoice information in this shared format, as well as the normal HTML and PDF, then this new format could then be consumed easily by services like Expensify, Mint, Quicken and what ever other services might help you manage your finances.   This scenario would be an achievable goal in my opinion and one that could quickly deliver real value.

Profiles can do that

There is no theoretical reason why this same goal could not be achieved by using generic hypermedia types and profiles .  However, you could now have the situation where Amazon likes using Hal, Staples decide on Siren for their company standard and NewEgg chose JSON-LD.  The theory of profiles, as I understand it, is that everyone should be able to consistently apply the same "invoice" profile across multiple base generic media types.  However, the consumers like Expensify and Mint are now faced with dealing with all these different base formats combined with profiles.  This seems like a significant amount of complexity for minimal gain.

But what about exploding media types

A common objection to creating media types that have a limited scope is the fear of "an explosion of media types".  The main concern here is multiple people creating media types that address the same purpose but have trivial differences.  Having one invoice format that has a property called "InvoiceDate" and another that has "dateInvoiced" is really not helping anyone. 

bigbang

Ironically, the competing generic hypermedia types that were partly a result of people trying to avoid creating an explosion of media types are now suffering from the "trivially different" problem.  Also, it is quite likely that the wide usage of schemas and profiles will suffer from APIs defining their own variants of semantically similar documents.

The important goal

Regardless of whether developers choose to use single purpose media types or generic hypermedia types with profiles, it is essential that we focus on creating artifacts that can be re-used across multiple APIs to enable sharing and integration that is "web scale".

Image Credit: Big bang https://flic.kr/p/cS8Hed