Notes from Kirsten Hunter, Designing Irresistible APIs, 30 September 2014
Speaker Slides

API should be a first-class product; without API you get code duplication. Etsy did API first.

Why have an API
Mobile/market penetration – good reason to have API, so you get consistency with your main product. Netflix made themselves industry standard on video devices by providing API
Drive usage – e.g. Twitter
Defensive strategy – get there first
Technical case – making the hard easy e.g. APIs for sending SMSs
Partner connectivity – once a partner has integrated your system it will put them off switching to another provider

Building your API
Use cases
If it’s easy for you to use the API, it will be easy for others.
Mobile developers care about one call per screen, and small payload because you’ve only got a small pipe

Architectural Considerations – Think usability rather than scalability: if no-one uses it you don’t have to worry about scalability!

Expressive queries
Netflix can extend queries to retrieve other data because the user needs a big pipe to use their product anyway
LinkedIn users want to chain things together

XML
Most developers are using compiled languages and will be happier with XML, but Twitter did switch to JSON
XML is painful in interpreted languages, they prefer JSON
JSON also better for mobile developers because of payload

Authentication and Authorisation – can control access to system

Copy – if there’s a similar API, make yours similar

Schema Modeling – e.g. with Blueprint, Swagger. It’s like the WSDL file was for SOAP

Design Driven Development – test your API against use cases

Developer Experience
Communication – explain how to use the API
Trust – consumer needs to believe company values the API
Asking Questions – a bad expectation on the user’s part is still a bug; need to manage their expectations
Getting started – if people can’t work out what it does and how to use it they’ll walk away
Example code
Resources – don’t make assumptions about what developers know, provide resources
Tools – e.g. so that they can look at an object
Support – how quickly will you respond

Versions
Every time you create a new version of an API you create technical debt
If you put the version in their URL they’ll never move to the new version
Deprecating old APIs is expensive – Twitter alienated a lot of developers and increased their support expense
(Audience member said you can actually make lots of backwards-compatible changes)