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: