Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
API Antipatterns
Search
Mike Pearce
March 26, 2012
Technology
3
240
API Antipatterns
Everyone *knows* how to build an API. This document describes how to NOT build one.
Mike Pearce
March 26, 2012
Tweet
Share
More Decks by Mike Pearce
See All by Mike Pearce
Being Agile
mikepearce
9
4.6k
How Big Is It? A guide to agile estimation and planning
mikepearce
5
870
Effective User Stories
mikepearce
2
240
Thimbl
mikepearce
1
150
UX for Developers
mikepearce
2
320
The Shu Ha Ri of Agile
mikepearce
1
620
The Anatomical Dissection of a Sprint Backlog
mikepearce
1
280
Other Decks in Technology
See All in Technology
Adminaで実現するISMS/SOC2運用の効率化 〜 アカウント管理編 〜
shonansurvivors
4
440
10年の共創が示す、これからの開発者と企業の関係 ~ Crossroad
soracom
PRO
1
720
社内お問い合わせBotの仕組みと学び
nish01
1
570
Where will it converge?
ibknadedeji
0
210
衛星画像超解像化によって実現する2D, 3D空間情報の即時生成と“AI as a Service”/ Real-time generation spatial data enabled_by satellite image super-resolution
lehupa
0
150
Vibe Coding Year in Review. From Karpathy to Real-World Agents by Niels Rolland, CEO Paatch
vcoisne
0
130
Oracle Base Database Service 技術詳細
oracle4engineer
PRO
11
80k
ACA でMAGI システムを社内で展開しようとした話
mappie_kochi
1
310
そのWAFのブロック、どう活かす? サービスを守るための実践的多層防御と思考法 / WAF blocks defense decision
kaminashi
0
160
OCI Network Firewall 概要
oracle4engineer
PRO
2
7.9k
業務効率化をさらに加速させる、ノーコードツールとStep Functionsのハイブリッド化
smt7174
2
130
スタートアップにおけるこれからの「データ整備」
shomaekawa
2
390
Featured
See All Featured
Reflections from 52 weeks, 52 projects
jeffersonlam
352
21k
Thoughts on Productivity
jonyablonski
70
4.9k
VelocityConf: Rendering Performance Case Studies
addyosmani
332
24k
Learning to Love Humans: Emotional Interface Design
aarron
274
41k
Facilitating Awesome Meetings
lara
56
6.6k
How GitHub (no longer) Works
holman
315
140k
Practical Orchestrator
shlominoach
190
11k
Typedesign – Prime Four
hannesfritz
42
2.8k
Site-Speed That Sticks
csswizardry
11
900
It's Worth the Effort
3n
187
28k
Bash Introduction
62gerente
615
210k
Cheating the UX When There Is Nothing More to Optimize - PixelPioneers
stephaniewalter
285
14k
Transcript
API Anti Patterns or, how to not f**k up your
API
API Anti Patterns or, how to not f**k up your
API
or, tips on how to annoy your API consumers
or, think you know REST? Awesome!
or, some of the crazy s**t people do with REST
Hello
Mike Pearce
http://social-network.com /MikePearce
http://social-network.com /MikeyPearce
http://social-network.com /mikepearce.net
http://social-network.com /MikePearce
An Apology
SONISPHERE @ Knebworth Flags should be banned a festivals!
Burritos: Best. Festival. Food. Ever.
None
Mike, Lee and Rog
SORRY
( ) HTTP REQUEST: That you get on with it...
Why am I here? REST
Why am I here? REST
Why am I here? REST Hah!
Why am I here? REST Huh?! ST
Do’s ✔
Do’s Dont’s ✔ ✘
Do’s Dont’s Whatevs.. ✔ ✘ ☠
But first... Some background
Who? Roy Fielding (the grandfather)
There!
Architectural Styles and the Design of Network- based Software Architectures
Can’t sleep? Read this...
None
A quick primer And now ...
REST != HTTP
REST != HTTP REST != The Web
REST
REST IS NOT
REST IS NOT HARD
REST IS NOT HARD Seriously!
Standards? We don’t need no steenkin’ standards!
MY CONSTRAINTS, LET ME SHOW YOU THEM
Some verbs...
Some nouns...
GET
PINT
PINT Please!
ANTI patterns Onto the main event
Overuse of ...
GET
None
Overuse of GET and POST or, GET/POST tunnelling.
None
None
BAD http://api.flickr.com/services/ rest/?method= flickr.photos.people.add &api_key=nnn&photo_id=yyy&u ser_id=xxx GET:
PUT: /user/MikePearce api_key=moo& age=33& size=medium& power=flight GOOD
PUT or POST? ASIDE PUT: /users/MikePearce PUT: /links/google PUT: /articles/100805/putorpost
PUT or POST? ASIDE POST: /documents/save name=styleguide.css& category=design
PUT or POST? ASIDE PUT when the resource will live
at the target URI POST when you want the server to handle the location of the resource.
POST: /dostuff/ user=MikePearce& action=delete& api_key=moo& token=quack& mode=3 BAD
GOOD DELETE: /user/MikePearce Wait! What? Why!?
Tunneling Errors through 200 OK?
Are you OK? I’m fine! Great! A 200 OK!
I’m fine! Are you OK? ARGGHH! He doesn’t understand me!
Great! A 200 OK!
This is better...
GET: /droid/r2d2 GET: /droid/c3po 404: Not the droids you’re looking
for
HTTP/1.1 200 OK Content-Type: text/plain <?xml version="1.0" encoding="UTF-8" ?> <response
code="error"> <error>Error!</error> <text>You have errored.</text> </response> What am I supposed to do with this?
RESPONSE CODES Which leads me nicely to...
IE has failed Informational
Success FTW!1
Redirection
Client Error (you try illustrating client error!)
Server Error It’s 1am. I can’t find an image for
server error.
HTTP/1.1 200 OK PUT: /user/MikePearce Meh..
HTTP/1.1 201 CREATED PUT: /user/MikePearce Huzzah!
HTTP/1.1 418 GET: /whatareyou
HTTP/1.1 418 I’m a teapot GET: /whatareyou This one is
real1!!
Caching
None
E-Tags
HTTP/1.1 304 NOT MODIFIED HTTP/1.1 200 OK Date: Mon, 23
May 2005 22:38:34 GMT Last-Modified: Wed, 08 Jan 2003 23:11:55 Etag: "3f80f-1b6-3e1cb03b" Connection: close Content-Type: text/html; charset=UTF-8
Mmm ... Delicious!
NO
HYPERMEDIA
HYPERMEDIA What is it?
HYPERMEDIA What is it?
HYPERMEDIA AS THE ENGINE OF APPLICATION STATE
oar...
HATEOAS (Remember hating oars)
Grey Areas
V3r510n1ng Versioning
GET: /user/MikePearce Him again. Prolific bastard.
GET: /user/MikePearce GET: /user/66
GET: /v1/user/MikePearce 1. Versioning with the URI GET: /v2/user/66
GET: /user/66 2. Not versioning the primary URI GET: /v1/user/MikePearce
GET: /user/66 3. No versioning
Document Extensions
Either
Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml
Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml or
Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml or Accept: text/xml Accept: application/json
SUM MARY Phew!
Overuse of GET and POST or, GET/POST tunnelling.
Tunneling Errors through 200 OK?
RESPONSE CODES Which leads me nicely to...
E-Tags
NO
HATEOAS (Remember hating oars)
V3r510n1ng Versioning
Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml or Accept: text/xml Accept: application/json
Any questions? (that I can answer!)
Photo Credits Wordle.net flickr.com/photos/wouterkiel/3717057757/ - Wouter Kiel flickr.com/photos/joe_13/19946186/ - joe_13
flickr.com/photos/23846880@N00/391925649/ - Rutger de Moddertukker flickr.com/photos/mararie/264942105/ - mararie flickr.com/photos/ndanger/7841795/ - ndanger flickr.com/photos/yourdon/2573762303/ - Ed Yourdon flickr.com/photos/thunderchild5/225675773/ - Thunderchild7 flickr.com/photos/duchamp/126115989/ - Duchamp flickr.com/photos/thefangmonster/490423135/ - The fang monster flickr.com/photos/nostri-imago/2894328425/ - cliff1066 flickr.com/photos/epsos/4582789354/ - epSos.de flickr.com/photos/projector/2092517108/ - allie pasquier flickr.com/photos/nickstone333/3135320160/ - nickstone333 flickr.com/photos/rdrcollection/116454033/ - Rodney Ramsey flickr.com/photos/christophercarfi/2730304130/ - Christophercarfi flickr.com/photos/turatti/4526352835/ - jaci xIII
Mike Pearce
[email protected]
mikepearce.net twtitter.com/mikepearce Thanks!