The document discusses best practices for API usage and management, emphasizing the importance of testing, versioning, and embracing standards to minimize failure opportunities. It provides five key tips: thorough testing, planning for future versions, embracing standards, continuous monitoring, and handling failures gracefully. Additionally, it suggests utilizing API management services for effective monitoring and support.

1. Whiskey,
Tango,
Foxtrot:
Understanding
API Usage
Clay Loveless
Chief Architect, Mashery
@claylo
OSCON
July 22 2010

2. APIs Gone Wild
If You Build It ... Itʼll Turn On You Someday

3. APIs Gone Wild
If You Build It ... Itʼll Turn On You Someday
GET
Overview
What Happens When Things 200
Go Wrong?
PUT
200
5 Tips to Stay Ahead
GET
200
The Secret 6th Tip
GET
503

4. Multiple Points of Failure
APIs Can Mean Exponential New Failure Opportunities

5. Multiple Points of Failure
APIs Can Mean Exponential New Failure Opportunities
Backend Systems
• DB Servers/Caches
• Hardware failures
• Power hiccups
• Incomplete reboots

6. Multiple Points of Failure
APIs Can Mean Exponential New Failure Opportunities
Backend Systems Interconnections
• DB Servers/Caches • Router failures
• Hardware failures • Bad cables
• Power hiccups • Severed internets
• Incomplete reboots • Remote-hands fail

7. Multiple Points of Failure
APIs Can Mean Exponential New Failure Opportunities
Backend Systems Interconnections External Deps
• DB Servers/Caches • Router failures • Fail Whales
• Hardware failures • Bad cables • Unannounced
• Power hiccups • Severed internets upgrades
• Incomplete reboots • Remote-hands fail • Random cloud
latency

8. Multiple Points of Failure
APIs Can Mean Exponential New Failure Opportunities
Backend Systems Interconnections External Deps
• DB Servers/Caches • Router failures • Fail Whales
• Hardware failures • Bad cables • Unannounced
• Power hiccups • Severed internets upgrades
• Incomplete reboots • Remote-hands fail • Random cloud
latency

9. The Retry Effect
“Try Again in a Few Moments” = Right Now
Successful Concurrent
600
450
Requests
300
150
Seconds

10. The Five Tips

11. Tip 1: Test It All
Seriously, Test It All

12. Tip 1: Test It All
Seriously, Test It All
Unit Tests Are Just the Beginning
If you donʼt have them yet, start
elsewhere

13. Tip 1: Test It All
Seriously, Test It All
Unit Tests Are Just the Beginning
If you donʼt have them yet, start
elsewhere
Test What Users Experience
End-to-End Black Box tests

14. Tip 1: Test It All
Seriously, Test It All
Unit Tests Are Just the Beginning
If you donʼt have them yet, start
elsewhere
Test What Users Experience
End-to-End Black Box tests
Replay Your Access Logs
More accurate than assumptions in
unit tests

15. Tip 1: Test It All
Seriously, Test It All
Unit Tests Are Just the Beginning
If you donʼt have them yet, start
elsewhere
Test What Users Experience
End-to-End Black Box tests
Replay Your Access Logs
More accurate than assumptions in
unit tests
Validate Return Payloads
A stack trace is not valid XML

16. Tip 2: Plan for Future Versions
The Sun Will Come Up Tomorrow

17. Tip 2: Plan for Future Versions
The Sun Will Come Up Tomorrow
Versions. Whoʼda thunk it?
Yes, versioning is useful beyond the
code powering your API.

18. Tip 2: Plan for Future Versions
The Sun Will Come Up Tomorrow
Versions. Whoʼda thunk it?
Yes, versioning is useful beyond the
code powering your API.
Versions Arenʼt Sexy/Semantic
Do it anyway, & stand up straight.

19. Tip 2: Plan for Future Versions
The Sun Will Come Up Tomorrow
Versions. Whoʼda thunk it?
Yes, versioning is useful beyond the
code powering your API.
Versions Arenʼt Sexy/Semantic
Do it anyway, & stand up straight.
Announce Versions Often
No one likes surprises when it
comes to API behavior.

20. Tip 3: Embrace Standards When Practical
APIs Are Better When Predictable

21. Tip 3: Embrace Standards When Practical
APIs Are Better When Predictable
Standard Approaches Mean Tools
Itʼs easier to monitor anomalies on
non-unique snowflakes.

22. Tip 3: Embrace Standards When Practical
APIs Are Better When Predictable
Standard Approaches Mean Tools
Itʼs easier to monitor anomalies on
non-unique snowflakes.
Avoid Uncomfortable Migrations
No one wants an OAuthpocalypse.

23. Tip 3: Embrace Standards When Practical
APIs Are Better When Predictable
Standard Approaches Mean Tools
Itʼs easier to monitor anomalies on
non-unique snowflakes.
Avoid Uncomfortable Migrations
No one wants an OAuthpocalypse.
Enhance Runtime Validation
Standards can make it easier to
detect+reject bogus calls earlier in
the request pipeline.

24. Tip 4: Monitor Everything & Be Honest
Slow Status Dashboards Suck More Than No Dashboard

25. Tip 4: Monitor Everything & Be Honest
Slow Status Dashboards Suck More Than No Dashboard
Test It All, All the Time
Better if you notice before your
users notice.

26. Tip 4: Monitor Everything & Be Honest
Slow Status Dashboards Suck More Than No Dashboard
Test It All, All the Time
Better if you notice before your
users notice.
Trends Are Your Friends
Canʼt spot trends without
continuous monitoring

27. Tip 4: Monitor Everything & Be Honest
Slow Status Dashboards Suck More Than No Dashboard
Test It All, All the Time
Better if you notice before your
users notice.
Trends Are Your Friends
Canʼt spot trends without
continuous monitoring
Fess Up Fast
No user wants to think theyʼre your
early-warning ops team.

28. Tip 4: Monitor Everything & Be Honest
Slow Status Dashboards Suck More Than No Dashboard
Test It All, All the Time
Better if you notice before your
users notice.
Trends Are Your Friends
Canʼt spot trends without
continuous monitoring
Fess Up Fast
No user wants to think theyʼre your
early-warning ops team.
Be Open Automatically
Real-time public health instills trust.

29. Tip 5: Fail Well
Donʼt Ice Me, Bro

30. Tip 5: Fail Well
Donʼt Ice Me, Bro
Well-formed Errors Win Friends
Developers are more tolerant of
failure if you anticipate the possibility.

31. Tip 5: Fail Well
Donʼt Ice Me, Bro
Well-formed Errors Win Friends
Developers are more tolerant of
failure if you anticipate the possibility.
Make Monitoring Easy
The more obvious the failure, the
easier it is to spot.

32. Tip 5: Fail Well
Donʼt Ice Me, Bro
Well-formed Errors Win Friends
Developers are more tolerant of
failure if you anticipate the possibility.
Make Monitoring Easy
The more obvious the failure, the
easier it is to spot.
Donʼt Punish Everyone
Determine who gets hurt most by
failures, and screw them last (or
not at all).

33. The Shameless Plug

34. Tip 6: Use an API Management Service
Like ... Mashery!

35. Tip 6: Use an API Management Service
Like ... Mashery!

36. Tip 6: Use an API Management Service
Like ... Mashery!
Managed API Service FTW
Use a service with active monitoring and
a support team. Let them call you first.

37. Tip 6: Use an API Management Service
Like ... Mashery!
Managed API Service FTW
Use a service with active monitoring and
a support team. Let them call you first.
Reports Covering Entire Ecosystem
Make sure reports & analytics cover the
entire spectrum of your APIʼs usage.

38. Tip 6: Use an API Management Service
Like ... Mashery!
Managed API Service FTW
Use a service with active monitoring and
a support team. Let them call you first.
Reports Covering Entire Ecosystem
Make sure reports & analytics cover the
entire spectrum of your APIʼs usage.
Get Help Building Meaningful Community
Nothing tells your developers you care like a
community with a pulse.

39. Did I Mention the Free Beer?
Free beer as in FREE BEER.
OSCON API Hour
7-9pm TONIGHT @ The EastBurn
1800 East Burnside Street
Just a 5 minute cab ride.
Mmm, beeer. And vintage games. Clay Loveless
Chief Architect
Wear Your OSCON Badge
2-3 drinks in, youʼll be happy clay@mashery.com
everyone has nametags. Twitter: @claylo