

Your API Consumers Aren’t Who You Think They Are - mikeknoop
http://bryanhelmig.com/your-api-consumers-arent-who-you-think-they-are

======
nadiac
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"

Edit : that resumes the issue I'm talking
[http://apijoy.tumblr.com/post/51977839347/when-you-didnt-
exp...](http://apijoy.tumblr.com/post/51977839347/when-you-didnt-expect-a-use-
of-your-api)

~~~
ismaelc
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.

Check out the feedback that makes this particular API much better than when it
was just launched [https://www.mashape.com/shepik/web-
screenshot#!issues?page=1...](https://www.mashape.com/shepik/web-
screenshot#!issues?page=1&tab=closed)

Disclaimer: I work for Mashape (an API Marketplace)

------
daurnimator
I infact constantly find the opposite.

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.

~~~
johns
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.

~~~
tokenizerrr
Your frontpage seems to have an &emdash; encoded incorrectly.

~~~
johns
Thanks, it's fixed now.

------
SatyajitSarangi
Excellent post.

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.

------
buro9
UX design has the concept of personas.

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.

------
kevinburke
We've seen this a lot in user testing at Twilio, and I tried to boil down a
lot of the info we saw into this talk, along the same lines as the post.

[http://www.confreaks.com/videos/2468-railsconf2013-how-to-
wr...](http://www.confreaks.com/videos/2468-railsconf2013-how-to-write-
documentation-for-people-that-don-t-read)

~~~
SatyajitSarangi
I forgot about Twilio's API. That's another good implementation. Even
Foursquare has an excellent API documentation. Instagram on the other hand...

------
contingencies
This seems like a reasonable place to remind people of the importance of
multilingual APIs/API documentation, too.

~~~
nadiac
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.

------
fragmede
I feel like this is the reason why ITTT is so popular.

