Product lessons: Building APIs for developers


“…the data returned doesn’t match the documentation…”
“When it’s complicated to get started…”

It seemed a logical stating point to ask (software) engineers what makes a good API experience in order to build one. The responses (some above) were mostly about letdowns & shortcomings.

Below is a list of product lessons I’ve come to learn during the development & iteration of the latest release of the PeerIndex API:

  • Start with empathy for the end user and take the time to understand their needs and what works for them, in this case, usually an overworked web developer
  • There’s lots of talented developers out there that could do mashups/cool things with your data, make it easy for them to create and play – quick to get an API key and start making calls – Sounds easy but you’d be amazed at how hard this is with some APIs
  • Write down and share the principles, strategy and roadmap for your API product – they act as a beacon of guidance when decisions need to be made¬†(something I got from Marty Cagan)
  • Get someone to help who does this day-in-day-out. At PeerIndex we work with¬†Mashery
  • If you do provide a good developer experience you will be recognised and thanked for it – it feels good
  • When you have a paid offering as part of your API, make sure you give people enough data for free to work out if they want to pay – we had signup buttons for our paid plans – how many people signed up by clicking those buttons? No-one. Let your end users/customers win first and win convincingly.
  • If your pricing structure isn’t working, change it – we initially had fixed price tiers until we found that the developers using the API were in two categories, those playing around/using data at low volume (not ready/wanting to pay) and high volume API partners.
  • If you’re lucky enough that someone takes the time to ask you a question about your API – take notice, something isn’t clear enough

This is not to say that the PeerIndex API is ‘done’.

It’s a product that needs to grow and evolve: more use cases (examples), more data exposed (more things for developers to play with) etc.

Useful resources:

Image credit:

Buzz words that aren’t going away

Gamification – “the concept of applying game-design thinking to non-game applications to make them more fun and engaging.” (defn.)

Good examples: Foursquare (earning badges and social kudos through checking in at locations), Nike+ (Turning running into a game, clock up miles and share your achievements with your friends)

More info on Gamification here.

A screenshot from a LinkedIn group I'm a member of

(Social) Influencer – A person who’s actions or activities (typically, those shared online) impact others within their network/community/area of expertise, either through raising awareness of said activities and/or driving action. (defn. mine)

I’ve seen examples popping up everywhere from the work I’m involved in at PeerIndex. Gamification also plays a big part in social influence platforms like PeerIndex and Klout – “Has my score gone up?” “What new topics am I recognised as influential in?”

Why is so much data being crunched on who is and isn’t an influencer (and in what context or community)? Well, achieving word of mouth advocacy through targeting and engaging influencers on social media is a powerful and more authentic way for brands to reach the masses – that’s something every brand wants a piece of, whether they know it yet or not.

More info on Influencer Marketing here.