Pragmatic RESTful API Design: Apigee Webinar
Upcoming SlideShare
Loading in...5
×
 

Pragmatic RESTful API Design: Apigee Webinar

on

  • 37,629 views

RESTful API design principle webinar by apigee. Check out our blog for the recording and video, thanks!

RESTful API design principle webinar by apigee. Check out our blog for the recording and video, thanks!

Statistics

Views

Total Views
37,629
Views on SlideShare
14,909
Embed Views
22,720

Actions

Likes
35
Downloads
409
Comments
0

32 Embeds 22,720

http://blog.apigee.com 19377
http://apigee.com 1598
https://kiwi.freenet-group.de 975
https://blog.apigee.com 343
http://blog.sonoasystems.com 197
http://www.techgig.com 55
http://mktg-dev.apigee.com 47
https://twitter.com 23
http://203.235.212.49:8080 17
http://mktg-dev.wearepropeople.md 17
url_unknown 14
http://translate.googleusercontent.com 11
http://webcache.googleusercontent.com 8
http://mktg.local 6
http://ip54.216-86-157.static.steadfast.net 4
https://abs.twimg.com 3
http://edit.apigee.net 3
http://203.235.212.49 3
https://www.facebook.com 2
http://ip52.216-86-157.static.steadfast.net 2
http://idc-iprism03 2
http://mktg-new.local 2
http://ip53.216-86-157.static.steadfast.net 2
http://131.253.14.98 1
http://moderation.local 1
http://www.linkedin.com 1
http://www.techgig.timesjobs.com 1
http://ip51.216-86-157.static.steadfast.net 1
http://ip51.216-86-157.static.steadfastdns.net 1
http://www.slideshare.net 1
http://172.26.102.57:15871 1
https://kiwiweb-test.mobilcom.de 1
More...

Accessibility

Categories

Upload Details

Uploaded via as Apple Keynote

Usage Rights

CC Attribution License

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • http://www.nordsc.com/ext/classification_of_http_based_apis.html\n
  • \n
  • Here’s an example SOAP request\n
  • Via uzbeckistan and \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • let’s understand how developers build apps.\n\ndevelopers work in a development cycle (sometimes formally, more often informally) with four 4 phases:\n\nrequirements gathering\ndesign\ndevelopment \nand testing\n\n\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • use facebook as versionless example being bad\n
  • no dots\n\nversion required\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • as they create applications, developers make hundreds or even thousands of simple decisions.\n\nthe faster they make decisions, the faster an app gets made.\n\nthe better the decisions they make, the better the app.\n\nHick’s law states that for simple stimulus-response tasks, the time it takes to make a decision is a function of the number of available options.\n\nThe more options we give our developers about our API the longer it will take them to build apps.\n\nlet’s take a look at an example where unnecessary complexity collides with Hick’s Law.\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • use facebook as versionless example being bad\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • use facebook as versionless example being bad\n
  • \n
  • \n
  • \n
  • \n
  • \n

Pragmatic RESTful API Design: Apigee Webinar Pragmatic RESTful API Design: Apigee Webinar Presentation Transcript

  • Pragma&c
RESTBeware
of
DogmaMarsh
Gardiner@earth2marshBrian
Mulloy@landlessnessApigee@apigee
  • #apidesign 2
  • 3
  • What
is
Pragma&c
REST?
  • What
is
Pragma&c
REST?• Not strict REST
  • What
is
Pragma&c
REST?• Not strict REST• Adoption-centered design
  • Why
REST
is
winning:
  • Why
REST
is
winning:http://api.twitter.com/1/statuses/public_timeline.json
  • POST /InStock HTTP/1.1Host: www.example.orgContent-Type: application/soap+xml; charset=utf-8Content-Length: 299<?xml version="1.0"?><soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> </soap:Header> <soap:Body> <m:GetStockPrice xmlns:m="http://www.example.org/stock"> <m:StockName>IBM</m:StockName> </m:GetStockPrice> </soap:Body></soap:Envelope>
  • URLs
and
Verbs
  • URLs
and
Verbs• URL is the LCD
  • URLs
and
Verbs• URL is the LCD• Verbs map to CRUD
  • Good Architecture ! Good Design
  • “ As
the
flexibility
of
a
system
increases,
its
usability
 decreases. Flexibility‐Usability
Tradeoff Universal
Principles
of
Design
  • “ Successful
products
typically
follow
four
stages
of
creaEon:
 requirements,
design,
development,
and
tes&ng. Development
Cycle Universal
Principles
of
Design
  • We
only
need
two
URLs.
  • The
first
is
for
a
collecEon.
  • /dogs
  • The
second
is
for
an
element.
  • /dogs/1234
  • POSTGETPUTDELETE
  • CREATEREADUPDATEDELETE
  • Resource POST GET PUT DELETE create read update delete create
a
new
 bulk
update
 delete
all
 /dogs list
dogs dog dogs dogs if
exists
 update
Bo/dogs/bo error show
Bo delete
Bo if
not error Wikipedia
  • Verbs
are
bad.
  • Nouns
are
good.
  • Plurals
are
beNer.
  • What
about
associaEons?
  • GET /owners/9876/dogsPOST /owners/9876/dogs
  • What
about
complex
variaEons?
  • Cody Simms
  • Sweep
variaEons
under
the
‘?’
  • /dogs?color=red&state=running&location=park
  • What
about
paginaEon?
  • FacebookoffsetlimitTwiNerpagerppLinkedInstartcount
  • /dogs?limit=25&offset=50
  • What
about
versioning?
  • earth2marsh
  • Twilio/2010-04-01/Accounts/salesforce.com/services/data/v20.0/sobjects/AccountFacebook?v=1.0
  • /v1/dogs
  • Please
give
me
exactly
what
I
need.
  • LinkedIn/people:(id,first-name,last-name,industry)Facebook
/joe.smith/friends?fields=id,name,pictureGoogle
(parEal
response)
?fields=title,media:group(media:thumbnail)
  • /dogs?fields=name,color,location
  • What
about
formats?
  • Google
Data?alt=jsonFoursquare/venue.jsonDigg*Accept: application/json?type=json* The type argument, if present, overrides the Accept header.
  • “ The
Eme
it
takes
to
make
a
decision
increases
as
the
 number
of
alternaEves
increases. Hick’s
Law Universal
Principles
of
Design
  • /dogs.json/dogs/bo.json
  • What
about
searching?
  • Global/search?q=fluffy+dogScoped/owners/bob/dogs/search?q=fluffyFormaNed/search.xml?q=fluffy
  • What
about
errors?
  • earth2marsh
  • Facebook HTTP Status Code: 200{"type":"OAuthException","message":"(#803) Someof the aliases you requested do not exist:foo.bar"}Twilio HTTP Status Code: 401{"status":401,"message":"Authenticate","code":20003,"more_info":"http://www.twilio.com/docs/errors/20003"}SimpleGeo HTTP Status Code: 401{"code":401,"message":"AuthenticationRequired"}
  • Code
for
code200 - OK401 - Unauthorizedhttp://en.wikipedia.org/wiki/List_of_HTTP_status_codesMessage
for
people{“message” : “Verbose, plain languagedescription of the problem with hints abouthow to fix it.”“more_info” : “http://dev.teachdogrest.com/errors/12345”}
  • What
about
the
rest
of
the
URL?
  • Facebook graph.facebook.com api.facebook.com developers.facebook.comFoursquare api.foursquare.com developers.foursquare.com TwiNer api.twitter.com search.twitter.com stream.twitter.com dev.twitter.com
  • API
gatewayapi.teachdogrest.comDeveloper
connecEondevelopers.teachdogrest.comDo
web
redirectsapi → developers (if from browser)dev → developersdeveloper → developers
  • What
about
defaults?
  • FormatjsonPaginaEon
(depends
on
data
size)limit=10&offset=0
  • What
about
excepEonal
stuff?
  • MiguelVieira
  • Client
intercepts
HTTP
error
codes
  • TwiNer/public_timelines.json?suppress_response_codes=trueHTTP Status Code: 200{"error" : "Could not authenticateyou." }
  • Always
returns
OK/dogs?suppress_response_codes=trueCode
for
code
ignoring200 - OKMessage
for
people
code{“response_code” : “401”, “message” :“Verbose, plain language description of theproblem with hints about how to fix it.”“more_info” : “http://dev.teachdogrest.com/errors/12345”, “code” : 12345}
  • Client
supports
limited
HTTP
methods
  • Method
Parametercreate/dogs?method=postread/dogsupdate/dogs/bo?method=put&location=parkdelete/dogs/bo?method=delete
  • Really?
All
of
this?
And
iterate
it?
  • Application API Virtualization LayerAPI API API
  • Be
RESTfulOnly
2
URLsNo
verbsUse
nouns
as
pluralsSweep
complexity
behind
the
‘?’Borrow
from
leading
APIsAccount
for
excepEonal
clientsAdd
virtualizaEon
layer
  • THANK
YOUQues%ons
and
ideas
to:#apidesignMarsh
Gardiner Brian
Mulloy@earth2marsh @landlessnessmarsh@apigee.com brian@apigee.com