api design anti-patterns
TRANSCRIPT
![Page 1: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/1.jpg)
API DESIGN ANTI-PATTERNS
Jason HarmonAPI Design @PayPal @Braintree
@jharmn
![Page 2: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/2.jpg)
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/channel/UCKK2ir0jqCvfB-kzBGka_Lg
![Page 3: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/3.jpg)
COLLECTOR OF MISTAKESJob #1 in creating consistent DX
![Page 4: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/4.jpg)
MIXED UPCONVENTION
SPath, query parameters,
headers, fieldsresourceNameresource-nameresource_name
PICK ONE, BE CONSISTENT!
![Page 5: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/5.jpg)
PARAMETER CONFUSIONPath, Query, Body, Header?
![Page 6: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/6.jpg)
• A few rules of thumb:
• Path: required, resource-identifier
• Query: optional, query collections
• Body: resource-specific/logic
• Header: global/platform-wide
API PARAMETERS
![Page 7: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/7.jpg)
JSON JUNK DRAWER
https://www.youtube.com/watch?v=-MBXsmSrKE8
REST API Design: Avoid future proofing with the JSON junk drawer
![Page 8: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/8.jpg)
JSON JUNK DRAWERTL;DR
Useful for client-defined fields/val-ues
Not a good way to extend your APIJust add fields to resposne
Don’t add new required fields to re-quests
![Page 9: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/9.jpg)
SEQUENTIALIDENTIFIERS/invoices/8765432Usually derived from database sequences
+1 each time a resource is created
![Page 10: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/10.jpg)
• https://www.owasp.org/index.php/Top_10_2010-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 OBJECTREFERENCE
![Page 11: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/11.jpg)
IDENTITY IN URLS/license?user=BR548076/license?token=E43FD312
/users/T22000129/license
![Page 12: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/12.jpg)
HTTP DEFINES AUTHhttp://tools.ietf.org/html/rfc7235#section-4.2
Use the Authorization header + token
![Page 13: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/13.jpg)
DON’T FORGET THE LOGSMost web servers/proxies/intermediaries log:Verb + URL, not often query, rarely headers
![Page 14: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/14.jpg)
RELAX.These are pretty easy fixes, if it’s not live yet (or v2).
Plus, there’s a bright future.
![Page 15: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/15.jpg)
DESIGN FIRSTThere’s really not a reasonable debate
![Page 16: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/16.jpg)
A DESIGN REMEDIALThinking developer experience
![Page 17: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/17.jpg)
DESIGN THINKING: RULESAPIs are for humans and machines
Innovate
The human rule• All design activity is ultimately social in
natureThe ambiguity rule• Design thinkers must preserve ambiguityThe re-design rule• All design is re-designThe tangibility rule• Making ideas tangible always facilitates
communication
![Page 18: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/18.jpg)
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
![Page 19: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/19.jpg)
AUTOMATESpec-driven development
}
![Page 20: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/20.jpg)
DESIGNCollaborate on new design in API spec
![Page 21: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/21.jpg)
GOVERNANCEValidate design against API standards
![Page 22: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/22.jpg)
CREATE STANDARDSMake the rules, and stick to them
![Page 23: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/23.jpg)
STANDARDSSome of the primary concerns
• Authentication/Authorization
• Versioning• Naming conventions
for URLs, parameters, headers
• Interaction patterns with verbs
• Paging/sorting• Hypermedia
semantics
![Page 24: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/24.jpg)
SHARE STANDARDS!If we all share, broad consistency can exist
PayPal API Style Guidehttps://devblog.paypal.com/paypals-api-style-guide
/
![Page 25: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/25.jpg)
DISCOVERRender specs in developer portal
Indicate planned APIs vs live
![Page 26: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/26.jpg)
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
![Page 27: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/27.jpg)
MOCKUse mock APIs from specs to get feedback
Samples are a great starting point
Image credit: https://www.flickr.com/photos/timthetrumpetguy/16081398370
![Page 28: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/28.jpg)
MOCKFake 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
![Page 29: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/29.jpg)
DEVELOPBuild APIs according to specs
Validate request/response in app from spec
![Page 30: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/30.jpg)
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
![Page 31: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/31.jpg)
VALIDATE DESIGNCheck request/response vs spec in acceptance tests
BDD FTW
![Page 32: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/32.jpg)
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
![Page 33: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/33.jpg)
GO LIVE!Be sure to integrate validation with CI
![Page 34: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/34.jpg)
WORKS AS DESIGNEDYou can still always screw up, so be smart
![Page 35: API Design Anti-Patterns](https://reader031.vdocuments.us/reader031/viewer/2022030221/588484e81a28ab6d1a8b4e55/html5/thumbnails/35.jpg)
Jason HarmonAPI Design @PayPal @Braintree
@jharmn