My feed reader, today, brought me this blog post from Ivanka Majic: “So, you want to provide an API for the world to use?”

It’s a blog post you have to read if you are interested in APIs. Her considerations are exactly what made us change our perspective and create the new version of Mashape, in the form of “API Marketplace”.

First of all, my considerations (and mashape itself) concern web based APIs, that are just a subset of APIs.

Ivanka in her blog post defines two problems for API providers.

“The first problem is to design the API. The second is to help people learn to use it.”

Let’s start from the second problem. She divides it in two subsections: Documentation and Support.

This is our view on how a API component should be documented:  http://www.mashape.com/component/Image%20Pack using Ivanka’s words this documentation  has an overview , is concise and logical  and  uses navigation to expose content. 

Or, at least, this is what we had in mind while we were designing that part :)

Tutorial and examples? Yes, mashape provides them too! Why is mashape, in part, the tutorial provider and not only the developer?

Let me explain: our approach enables a developer to publish a component accessible via REST APIs in minutes: he has to download our server library, to configure it (adding his component’s logic) and to register it on mashape

I understand our server library is something not everyone wants to use (and we are actually providing only the PHP version during this alpha version..) but it helps API providers in another way: it defines a standard way to interact with that API. The first time a developer uses a component from mashape he will need some minutes, reading generic documentation from mashape and specific documentation for that component. The second time he will be able to access it in much less time.

When our platform will be more stable, we will be able to add client libraries, in this way a final user will have access, hopefully, to tons of different APIs in a standard way, a sort of framework to consume APIs.

And what about the first problem Ivanka points out (API design)? Well, this server library helps a lot during API designing process! But not solves it, obviously, because is too bounded to the coding style of the developer.

Let’s try to improve APIs world! :)