What all APIs still look like as WebPages

... or how far we are from the human web.

This is part of a series. You want to read this before carrying on.

On my last post, I tried to show you what your web API looks like to a web developer. On this post, I'll go over what your L3 API STILL looks like to a web developer.

Here are a few things we take for granted on the web that makes our APIs feel like they were designed back in 1995.

Websites are always at HEAD: The Versionless API challenge

Now whether you are a L3 API or not, we still live in a world that APIs are versioned and moving from one version to another is done out of band.

There is a premise that hypermedia APIs make transitioning from one version to another a lot easier, mostly due to the fact that you are under the control of the links.

But still, there are plenty of problems to be resolved (e.g. changing cardinality of your properties, changing your schema in a non-backward compatible manner, etc), and this is one of those promises that we'll have to let time be the judge.

Show me a respectable API, with millions of users, who has transitioned through 3-4 different versions, over more than 2-3 years, and you can call this problem done.

This is how absurd your APIs currently look like to an user of the human web:

http://example.org/index.html

Hi, welcome to our website!

Our website has multiple versions, click here to continue:

My website v1
My website v2
My website v3

The Discovery of APIs challenge

One of the biggest challenges about existing APIs is that they are non-discoverable. There is no "crawler" equivalent for APIs. Part of the problem is that they are entirely disconnected from the human web.

What that means is that, in order for me to use your API, I actually have to go to your website and read your documentation in English, rather than finding it programatically.

What we need is a google.com-like crawler for APIs (and hopefully we've learned from UDDI and the register-vs-crawl battle).

Your APIs looks like those websites that are entirely irrelevant to search engines, those that you have to copy-past the URL to get to it.

http://example.org/index.html

I have no idea how you got here, but welcome to our website!

The Vocabulary Fragmentation challenge

The third biggest challenge with your API right now is that it is in Klingon. Yeah, that's right, I don't understand a word of what's written over there, because we are not using the same vocabulary.

We need a language that everybody speak, that everybody can understand. Something like latim.

http://example.org/index.html

The Verb Taxonomy Fragmentation challenge

The fourth challenge is that your API is trying to give me affordances that I don't understand. Stop trying to make fetch happen, it is not going to happen.

We need to agree on a set of affordances that we all understand. Sort of what GET/POST/DELETE/PATCH is for HTTP, but at the application semantic level.

http://example.org/index.html

Welcome to my website! Fill the following form to "fetch" our products!

The Hypermedia media type fragmentation challenge

Fragmentation is certainly an important step that needs to be taken before unification. We need diversity and we need exploration. I love seing efforts like hydra, uber, hal and siren to pop up!

But at some point in time, we need to converge into a unified media type. Like text/html is for the human web.

http://example.org/index.html

The API Management challenge

Finally, managing APIs is done completely different than managing web sites. That's insane. You have to sign-up to an API key before you even use an API? When was the last time that you've seem that on a website?

http://example.org/index.html

Welcome to our website! We have detected that you are coming from a corporate IP!

Unfortunately, you can't use our website until your company signs some paperwork up front.

Could you please ask your company to get their "API KEYS" so that we can apply quotas and throttle?

So, where we go from here?

As usual, follow your nose :) Be part of the dialogue! If you have ideas on how to address these things, lets talk, I'd like to learn about them!

This is part of a series of posts. You can read more about that here.