API DESIGN ANTI-

PATTERNSJason Harmon

API Design @PayPal @Braintree@jharmn

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

COLLECTOR OF

MISTAKESJob #1 in creating consistent DX

MIXED UPCONVENTION

SPath, query parameters,

headers, fields

resourceName

resource-name

resource_name

PICK ONE, BE

CONSISTENT!

PARAMETER

CONFUSIONPath, Query, Body, Header?

• A few rules of thumb:

• Path: required, resource-identifier

• Query: optional, query collections

• Body: resource-specific/logic

• Header: global/platform-wide

API PARAMETERS

SEQUENTIAL

IDENTIFIERS

/invoices/8765432

Usually derived from database sequences

+1 each time a resource is created

• 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

IDENTITY IN URLS/license?user=T22000129/license?token=E43FD312

/users/T22000129/license

HTTP DEFINES AUTHhttp://tools.ietf.org/html/rfc7235#section-4.2

Use the Authorization header + token

DON’T FORGET THE

LOGSMost web servers/proxies/intermediaries log:Verb + URL, not often query, rarely headers

RELAX.These are pretty easy fixes

CREATE STANDARDSMake the rules, and stick to them

Jason Harmon

API Design @PayPal @Braintree

@jharmn