What does a developer expect from an API supplier?
Here is my proposal for a developer API pyramid hierarchy of needs that you have to read from the bottom up.
The model is inspired by the Maslow original pyramid of human needs and requires that each level of needs be fully satisfied before moving up one level.
If you satisfy one of the top levels but you happen not to respect a condition from a lower level L, you automatically get downgraded to the level L-1, even if you satisfy the majority of needs in the upper levels. So every level is exclusive.
The following hierarchy was made with the mind of a developer who has business expectations. It goes from the wow-this-API-provides-access-to-data-that-rocks mindset to the my-business-relies-on-that-API-and-my-customers-love-it mindset.
Access: does the API exist?
The purpose of an API is to share data or functionality. If there is not even a minimum viable interface for developers to access the data, there is no API. So, at this level, it is often an alpha version without any application design, some even share a FTP.
Here the reaction may be: cool data, but they didn’t make their work properly :(
Consistency: is the API consistent?
Now developers want some architecture or protocols to go fast in API usage and want some reliable performance to think to use the API in production. It is often the beta phase.
The reaction would be here : yes nice API! i maybe use it in the future when it would be complete.
Design and documentation: is the API developer-friendly?
Now the API has some status history, performance management and API team begin to make it developer friendly with URL design, interactive documentation, code samples, exploration console, SDK for many languages, and prooves of investment in community with forum and support. This is the phase of new release with versionning and suffisant time to completely update to the new version with deprecated time.
The first reaction here would be : Wow this API rocks ! Is it free? what is the quota/rate limit? :)
Policy and business model: is the API model enables me to use it like i would?
Here is the business phase to give some prospective to developers about the API policy and trustness on API in business.
Here terms and conditions are clarified, quota or rate limit well defined and a business model is proposed on whom developers can invest time and money in creating a viable business and plan some future on it.
The policy and business model may evolve, but a company which would change terms and conditions without any warnings or which would make changes that highly perturbs existing businesses or even break them could not go up this level.
The first reaction here would be here : Great API. I have an idea of application !
Confidence: do I trust the company which provide it that will keep all things well for me in the future?
Now we are speaking about global trustness. Here a developper will check status history, roadmap, API team involvment, in blogging and evangelism, developers community ecosystem of existing and running applications, growth of the company which provide this API.
For a non profitable company or an emerging start-up is hard to be in this step because the forecast is hard to draw for making some projections. To be there, the API policy or pricing has to not have changed for a long time in a way that has perturbed the ecosystem.
The reaction here could be : “They understood developers, they made everything to ease me to use their API. I have an idea of a company ! I realised that no existing solution exists for ….”
API neutrality: do I invest my time and my money on this business?
Here is the “all you expect API”.
This step is today I think only reserved to API-driven company or companies which ARE an API and sell it only. At this step, policy of the API is very open and prooves that it would be in long time. The business model is a proven one and viable to ensure everybody that it will not change, often in a pay-as-you-go model.
Beware of non-profitable companies
Free Open APIs of companies which are not profitable could not be in this category, because they are at the mercy of investors short-term strategy and have proven in the past that they were not trustable.