Common issues found in API designs proposed by developers at PayPal (and elsewhere!), along with some solutions.

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. SEQUENTIAL
IDENTIFIERS
/invoices/8765432
Usually derived from
database sequences
+1 each time a resource is
created

8. • 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

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

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

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

12. RELAX.
These are pretty easy fixes

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

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