Talk from the Auckland API and microservices meetup 10/20/15 http://www.meetup.com/Auckland-API-and-Microservices-Meetup/events/225828804/ Beyond specific anti-patterns, we also covered API design-first development process, and how to utilize spec formats and feedback loops to produce higher quality APIs.

1. API DESIGN ANTI-
PATTERNS
Jason Harmon
API Design @PayPal @Braintree
@jharmn

2. JASON
HARMON
• From Austin, TX
• Head of API Design at PayPal
• Moving into Braintree
• Blogger at apiux.com,
pragmaticapi.com
• Organizer austinapi.com
meetup
• Youtube: API Workshop
• https://www.youtube.com/ch
annel/UCKK2ir0jqCvfB-
kzBGka_Lg

3. COLLECTOR OF
MISTAKESJob #1 in creating consistent DX

4. MIXED UP
CONVENTION
S
Path, query parameters,
headers, fields
resourceName
resource-name
resource_name
PICK ONE, BE
CONSISTENT!

5. PARAMETER
CONFUSIONPath, Query, Body, Header?

6. • A few rules of thumb:
• Path: required, resource-identifier
• Query: optional, query collections
• Body: resource-specific/logic
• Header: global/platform-wide
API PARAMETERS

7. JSON JUNK DRAWER
https://www.youtube.com/watch?v=-
MBXsmSrKE8
REST API Design: Avoid future proofing with the JSON junk
drawer

8. JSON JUNK DRAWER
TL;DR
Useful for client-defined fields/values
Not a good way to extend your API
Just add fields to resposne
Don’t add new required fields to request
s

9. SEQUENTIAL
IDENTIFIERS
/invoices/8765432
Usually derived from
database sequences
+1 each time a resource is
created

10. • https://www.owasp.org/index.php/Top_10_20
10-A4-Insecure_Direct_Object_References
• Developers suck at securing resources
• Better to use non-sequential strings for
resource IDs
• UUID/GUID is an obvious option
INSECURE DIRECT OBJECT
REFERENCE

11. IDENTITY IN URLS
/license?user=BR548076
/license?token=E43FD312
/users/T22000129/license

12. HTTP DEFINES AUTH
http://tools.ietf.org/html/rfc7235#section-4.2
Use the Authorization header + token

13. DON’T FORGET THE
LOGSMost web servers/proxies/intermediaries log:
Verb + URL, not often query, rarely headers

14. RELAX.
These are pretty easy fixes, if it’s not live yet (or
v2).
Plus, there’s a bright future.

15. DESIGN FIRST
There’s really not a reasonable debate

16. A DESIGN REMEDIAL
Thinking developer experience

17. DESIGN THINKING:
RULESAPIs are for humans and machines
Innovate
The human rule
• All design activity is ultimately social in nature
The ambiguity rule
• Design thinkers must preserve ambiguity
The re-design rule
• All design is re-design
The tangibility rule
• Making ideas tangible always facilitates
communication

18. DESIGN THINKING:
TOOLS
• Understanding your audiences
thoughts, desires, beliefs and actions
• Co-creating outcomes with that
audience
• Creating early versions or prototypes
and testing for fit / relevance /
acceptability
• Root cause analysis, five whys,
mindmapping

19. AUTOMATE
Spec-driven development

20. DESIGN
Collaborate on new design in API spec

21. GOVERNANCE
Validate design against API standards

22. CREATE STANDARDS
Make the rules, and stick to them

23. STANDARDS
Some of the primary concerns
• Authentication/Authorizat
ion
• Versioning
• Naming conventions for
URLs, parameters,
headers
• Interaction patterns with
verbs
• Paging/sorting
• Hypermedia semantics

24. SHARE STANDARDS!
If we all share, broad consistency can exist
PayPal API Style Guide
https://devblog.paypal.com/paypals-api-style-guide/

25. DISCOVER
Render specs in developer portal
Indicate planned APIs vs live

26. VISUALIZE SPECS
Many open source options
• Swagger-UI
• RAML API Portal
• Apiary
• Numerous options on
Github
• Host it and make it known
Hosted services
• Example: http://gelato.io

27. MOCK
Use mock APIs from specs to get feedback
Samples are a great starting point
Image credit: https://www.flickr.com/photos/timthetrumpetguy/160813983
70

28. MOCK
Fake it ‘til you make it
Again, many open source
options
• Swagger, RAML, Blueprint
all have Github projects
Custom-build
• Define controllers
• Link responses to samples
Host
• Make URLs available to
clients for feedback

29. DEVELOP
Build APIs according to specs
Validate request/response in app from spec

30. DEVELOP/VALIDATE
Validate request/response
against spec in acceptance
tests
• Emerging area in open
source
Validate request in API against
spec
• Also, emerging area in
some languages
• Potentially processable in
proxy/facade layer

31. VALIDATE DESIGN
Check request/response vs spec in acceptance
tests
BDD FTW

32. ACCEPTANCE TESTING
API acceptance testing means HTTP
clients
• Not to say you shouldn’t do unit
testing
Define english-readable acceptance
criteria
• BDD approaches work remarkably
well
• Chakram JS is a great way to start
Ensure visibility
• Integrate into CI
• Test failures should indicate what’s
wrong to anyone
• Product should only accept stories
when tests are green

33. GO LIVE!
Be sure to integrate validation with CI

34. WORKS AS DESIGNED
You can still always screw up, so be smart

35. Jason Harmon
API Design @PayPal @Braintree
@jharmn