Web API maturity model

Web APIs (REST-based HTTP services with simple payloads, typically JSON) have proven to be a very simple and effective way for applications to consume capabilities provided by apps or expose some capabilities themselves. As we've experienced, there are various ways these APIs are defined from satisfying a large audience based on a single server (Twitter) to something more general that handles various kinds of resources and operations.

The reality of many of these Web APIs, their purpose and needs have evolved from their early inception and then evolving into their latest 3.1 version with additional bells and whistles, deprecating some baggage along the way.

So the title of this post is "Web API maturity model", so what is this and why is it needed?  Perhaps maturity model isn't the right title for it, let me describe the aspects of it and give some examples.  This looks a bit beyond Martin Fowler's article about this to go beyond his levels.

Basically it is a way to talk about how Web APIs are development and the various needs as the customer needs evolve and therefore the APIs evolve to meet those needs.

Maturity levels (loosely sketched out as):

1. REST+JSON (barely docs) - this is barebones, your app defines a simple Web API.  The goals at this level are not to make it rock solid and cover ever edge case but instead to focus on supporting an important scenario quickly, getting feedback on usage and evolve from there (if needed).  You rely on a sample, an incomplete wiki page or reading the source to figure out how best to use it.
2. REST+JSON (better docs, source) - a better web page dedicated to describing the API, samples and some source.  At this point you are promoting it a bit more as "the API" for your service.
3. REST+JSON (LD, docs, source) - needing a way to describe the payloads more consistently between various endpoints, could reuse existing vocabularies such as schema.org.  App developers may even want to share some of their vocabularies or capabilities
4. LDP (REST+JSON-LD&Turtle+containers) - needing a way to have a consistent pattern for interacting with "buckets" of like resources
5. Domain extensions (OSLC, etc) - needs around app development, systems engineering, ... which could create new vocabularies or capabilities themselves

In fact, these layers of maturity can be cleanly applied on one another without disrupting previous apps that consume the API.

Some may say "ya, dumbass this is just how we work", which they are right (at least not the dumbass part).  We often start small, find what works and evolve from it.  Though it is good sometimes to be clear and intentional in that is how you plan to operate as some look building integration APIs in a way that starts in the middle or end, instead of at level 1.  Though learning about various techniques and technologies in other levels helps guide developers to upgrade their mental toolbox of skills.

The levels I highlighted are just examples, incomplete and could even be viewed that there are different axis that might emerge.  Related to that is understanding in what scenarios stepping up the levels, or over to another axis, may make sense.  I plan to explore some more of these ideas, including how best to define, present, collaborate, evolve, enable all this. 

As always, interested to hear feedback (I prefer agreement but accept other forms as well)