API DESIGN ANTI-PATTERNS

Jason HarmonAPI 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/channel/UCKK2ir0jqCvfB-kzBGka_Lg

COLLECTOR OF MISTAKESJob #1 in creating consistent DX

MIXED UPCONVENTION

SPath, query parameters,

headers, fieldsresourceNameresource-nameresource_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

JSON JUNK DRAWER

https://www.youtube.com/watch?v=-MBXsmSrKE8

REST API Design: Avoid future proofing with the JSON junk drawer

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

SEQUENTIALIDENTIFIERS/invoices/8765432Usually derived from database sequences

+1 each time a resource is created

• 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

IDENTITY IN URLS/license?user=BR548076/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, if it’s not live yet (or v2).

Plus, there’s a bright future.

DESIGN FIRSTThere’s really not a reasonable debate

A DESIGN REMEDIALThinking developer experience

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

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

AUTOMATESpec-driven development

}

DESIGNCollaborate on new design in API spec

GOVERNANCEValidate design against API standards

CREATE STANDARDSMake the rules, and stick to them

STANDARDSSome of the primary concerns

• Authentication/Authorization

• Versioning• Naming conventions

for URLs, parameters, headers

• Interaction patterns with verbs

• Paging/sorting• Hypermedia

semantics

SHARE STANDARDS!If we all share, broad consistency can exist

PayPal API Style Guidehttps://devblog.paypal.com/paypals-api-style-guide

/

DISCOVERRender specs in developer portal

Indicate planned APIs vs live

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

MOCKUse mock APIs from specs to get feedback

Samples are a great starting point

Image credit: https://www.flickr.com/photos/timthetrumpetguy/16081398370

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

DEVELOPBuild APIs according to specs

Validate request/response in app from spec

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

VALIDATE DESIGNCheck request/response vs spec in acceptance tests

BDD FTW

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

GO LIVE!Be sure to integrate validation with CI

WORKS AS DESIGNEDYou can still always screw up, so be smart

Jason HarmonAPI Design @PayPal @Braintree

@jharmn