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