DO’S AND DON’TS OF APIS
Jason HarmonAPI Design @PayPal @Braintree
@jharmn
JASON HARMON
• API Design @PayPal @Braintree
• Blogger at apiux.com, pragmaticapi.com
COLLECTOR OF MISTAKESJob #1 in creating consistent DX
DON’TLet’s start with the bad news
#1: Design by facsimile
GOOD ARTISTS COPY, GREAT ARTISTS STEAL.
• Everyone does a survey of popular APIs to get started
• The difference between popular and useful for your customers can be huge
POPULAR MUST BE GOOD• Step #1 in designing
an API: look at popular APIs
• Facebook and Twitter probably aren’t good designs for your case • Use cases are rather
unique to social media
• Always consider vintage of design when surveying APIs
RISKS OF CARBON COPY DESIGN
• Imitating outdated design concepts
• Utilizing security patterns which are not appropriate for your customer’s scenarios
• Not taking advantage of HTTP
A BETTER APPROACH• Learn the fundamentals
of HTTP• Review API style guides
• Heroku, White House, PayPal, Cisco
• Understand why certain design approaches were used
• Listen to customers (more on this later)
#2: Build it and they will come
SAME OLD STORY
• Build API• Slap reference docs
together• Send email/write blog
post• Profit!
DEVELOPER PORTALMORE THAN REFERENCE
• Reference: only step #1
• Tell the story of what your product does
• Showcase how your API can be used
• Guides with code samples for easy onboarding
COMMUNICATION IS KEY• Ensure developers’
success• Blog + feedback• Twitter• Chat• Support channels• Surveys
• Listen to feedback, and address it fairly
DEVELOPER MARKETING:THE STRUGGLE IS REAL
• Hackathons
• Less of an effective option in recent times
• Evangelism
• Blogging, support, docs, meetups, events etc
• Integration marketing
• Make your API available on other platforms
• Examples: IFTTT, Slack App Directory
#3: Build your own API management
MORE THAN JUST A PROXY• Caching• DDoS protection• Tokens/Auth/Security• Quotas/Rate
limiting/Throttling• Policies/Tiers• Analytics
RISKS
• Insecure implementation
• Lack of advanced protections
• Low visibility to traffic patterns
• Lack of team focus
Stick to what you’re good at
OPTIONS
• Vendors
• 3scale, Apigee, Mashery, etc
• Open Source
• Kong from Mashape
DOThings to do from the start
#1: Comprehensive testing
No reason for production escapes with APIs
TYPES OF TESTING• Unit testing
• Fine for developer-centric view
• Acceptance testing• Definition of API
behavior usable by the whole team
ACCEPTANCE TESTINGFOR APIS
• HTTP calls made against your API
• Human-readable description of customer-driven scenarios
• Team should agree on language before building
• Behavior driven development (BDD) fits naturally
• Chakram is a great starting point
• https://github.com/dareid/chakram
#2: Listen to customers
BEFORE• Interview customers• Find out critical use
cases• Get on-the-ground
feedback for existing APIs before any new versions
• Write stories that sound like stories, not calls
DURING• Sync up with select group
of customers from early feedback• Offer mock APIs and
prototypes for testing with select customers
• Provide previews of developer portal, SDKs, whatever you have planned
• Look for partnership opportunities• Beware: deadlines may
find their way in!
AFTER• Focus on production feedback
loops• Interact on channels where
developers live (Stackoverflow, Twitter, Slack, etc)
• Dedicate staff/budget to collating feedback
• FIX BUGS as a top priority• You fought hard to get
adoption, don’t forget retention!
• Use feedback to help drive future roadmap
ANALYTICSSTALK YOUR CUSTOMERS• Monitor analytics to see who top users are• Reach out to find out
what they need to further succeed
• Look for customers who never succeed• Ask them if they need
help with anything, offer common solutions to their problems
#3: Build APIs for humans and machines
DEVELOPER EXPERIENCELANGUAGE MATTERS
• Use customer language when designing APIs• No internal lingo or
abbreviations• Use consistent
terminology between API design, reference, guidance, SDKs etc
DEVELOPER EXPERIENCEMORE THAN PORTALS• What does client code look like?
• “Dog fooding” - use new APIs internally, even if it’s just in exercises
• Build sample applications and share
• Compromises between terse client code and HTTP-friendliness are hard
• Consider SDKs • One of the first things
developers look for• HTTP literacy is on the rise,
this trend may change
Let’s wrap it up
APIS ARE A PRODUCT
• Market research
• Customer feedback
• Timely and helpful support
• Relationship building
Jason HarmonAPI Design @PayPal @Braintree
@jharmn
Recommended