When you design your APIs, you put a paradigm into depending who will be your user.
I know for example a Hotel booking API which for the same resources expose 3 differents API depending on their final users.
They have one design for airplane tickets services (which requires sector-specific naming standards), one other for other Hotel booking sites and a last one for long tail developers.
It is the same ressources but 3 differents APIs for exposing it, because they know their user needs.
I just think that when you design your API before knowing your user/customers, your users will be as you said in the article "not who you think they are"
A famous chinese proverb: "if you don't know where you are going, you will always arrive in a wrong place"
I think we also shouldn't underestimate the power of feedback, to help you tweak the API along the way. It's almost impossible to get it right the first time.
APIs documentation and forums help the lay-coder, but don't help me at all with trying to pin down a wire-format, or clear up an ambiguity in the docs.
Yes, because lot of people don't make the job to go out of the building and talk to their users.
They make a neutral interface, for everybody. This is why sometime their API seems not consitent with the real need that they solve for your application/business.
This is one of the reasons we built Runscope (yes, shameless plug). Seems like no amount of documentational diligence will completely prevent wire gremlins. Whether its faulty SDKs, typos, etc. if you can't see what's on the wire and share that with the party on the other end you'll waste hours debugging unfixable problems.
I created JustMigrate so I had to work with APIs of Tumblr and Posterous. Having had experience in building APIs and working with APIs of almost all the premium/famous/infamous services around, I was shocked when I came across Posterous API documentation.
Shocked in a beautiful way, as I couldn't believe how easy it was to understand. The API had realtime implementations right there, where you can enter values and check the response that you are getting.
Most API developers except users to use some scripting language or Poster to deal with the APIs to understand the response. Sometimes they give away code snippets, some of the times they will list down all the libraries that people built on top of the API, thus ensuring that the documentation bulk was the responsibility of the library developers. I was glad to see Posterous didnt' stick to that norm.
They act like unit tests, an insurance policy against scope creep in the UX that serves no-one (or at least, not your customers) and in essence break the API goals.
The key to personas is to create an idea of the end user, one persona per category of users. You may have power users, lay users, and non-developers.
These personas should be quite concrete... give them a name, a face, and age, a story.
Then, when you are building the UX hold up the proposal and ask "Did we do good by Tom, Sally and Robert?". If the answer is no to any, you may have a problem, and if it's no to all you definitely have a problem.
Personas help ensure the UX keeps solving user problems. Making their life easier.
I would think that as APIs are to help solves problems and make life easier, that personas could be used here too... to create a strong idea of the people that do use an API.
So long as the personas are honest... and really reflect who your users will be, or are... then it should help you create the right documentation and API for them.
Still depending of your users. Ir your users prefers an other language than english, do it. It can be a competititve advantage.
But be sure to know your users to do that, because english is ruling the API documentation world.
They have one design for airplane tickets services (which requires sector-specific naming standards), one other for other Hotel booking sites and a last one for long tail developers. It is the same ressources but 3 differents APIs for exposing it, because they know their user needs.
I just think that when you design your API before knowing your user/customers, your users will be as you said in the article "not who you think they are"
A famous chinese proverb: "if you don't know where you are going, you will always arrive in a wrong place"
Edit : that resumes the issue I'm talking http://apijoy.tumblr.com/post/51977839347/when-you-didnt-exp...