RESTful Best Practices-V1 1

RESTful Service Best Practices

Recommendations for Creating Web Services
Todd Fredrich
Pearson eCollege
toddf@ecollege.com
www.RestApiTutorial.com
05/29/12 www.RestApiTutorial.com Page 1 of 34
Table of Contents
Document istor!...................................................................................................................................... 5
"#o $#oul% Rea% T#is Document.............................................................................................................5
&ntro%uction................................................................................................................................................ '
"#at is R($T)........................................................................................................................................... '
*niform &nterface.................................................................................................................................. +
Resource,-ase%................................................................................................................................ +
.anipulation of Resources T#roug# Representations......................................................................+
$elf,%escripti/e .essages................................................................................................................ +
!perme%ia as t#e (ngine of Application $tate 0AT(1A$2......................................................... +
$tateless................................................................................................................................................. +
3ac#ea4le.............................................................................................................................................. 5
3lient6ser/er......................................................................................................................................... 5
7a!ere% s!stem......................................................................................................................................5
3o%e on %eman% 0optional2................................................................................................................... 5
R($T 8uic9 Tips....................................................................................................................................... 9
*se TTP :er4s to .ean $omet#ing................................................................................................... 9
$ensi4le Resource ;ames..................................................................................................................... 9
<.7 an% =$1;..................................................................................................................................... 9
3reate >ine,?raine% Resources...........................................................................................................10
3onsi%er 3onnecte%ness......................................................................................................................10
Definitions................................................................................................................................................10
&%empotence........................................................................................................................................ 10
$afet!................................................................................................................................................... 11
TTP :er4s.............................................................................................................................................. 11
?(T..................................................................................................................................................... 11
P*T..................................................................................................................................................... 12
P1$T................................................................................................................................................... 12
P*T /s P1$T for 3reation.................................................................................................................. 13
D(7(T(.............................................................................................................................................. 13
Resource ;aming..................................................................................................................................... 14
Resource *R& (@amples..................................................................................................................... 15
Resource ;aming Anti,Patterns.......................................................................................................... 1'
PluraliAation.........................................................................................................................................1'
Returning Representations....................................................................................................................... 1+
Resource Disco/era4ilit! T#roug# 7in9s 0AT(1A$ contB%2........................................................... 15
.inimal 7in9ing Recommen%ations.............................................................................................. 19
7in9 >ormat.................................................................................................................................... 19
"rappe% Responses.............................................................................................................................21
an%ling 3ross,Domain &ssues........................................................................................................... 22
$upporting 31R$........................................................................................................................... 22
$upporting =$1;P..........................................................................................................................22
8uer!ingC >iltering an% Pagination.......................................................................................................... 23
7imiting Results.................................................................................................................................. 24
7imiting /ia t#e Range ea%er.......................................................................................................25
7imiting /ia 8uer!,$tring Parameters............................................................................................25
Range,-ase% Responses................................................................................................................. 25
Pagination............................................................................................................................................ 2'
>iltering an% $orting Results............................................................................................................... 2+
>iltering.......................................................................................................................................... 2+
$orting............................................................................................................................................ 25
$er/ice :ersioning................................................................................................................................... 25
Date/Time an%ling................................................................................................................................. 29
Date/Time $erialiAation &n -o%! 3ontent........................................................................................... 29
Date/Time $erialiAation &n TTP ea%ers..........................................................................................29
$ecuring $er/ices..................................................................................................................................... 30
Aut#entication..................................................................................................................................... 30
Transport $ecurit!............................................................................................................................... 30
Aut#oriAation.......................................................................................................................................31
Application $ecurit!............................................................................................................................31
3ac#ing an% $cala4ilit!........................................................................................................................... 31
T#e (Tag ea%er............................................................................................................................ 32
TTP $tatus 3o%es 0Top 102................................................................................................................... 33
A%%itional Resources............................................................................................................................... 34
-oo9s...................................................................................................................................................34
"e4sites...............................................................................................................................................34
Document History
Date Version Description
>e4 10C 2012 Draft &nitial %raft /ersion.
Apr 24C 2012 /1.0 &nitial pu4lic 0non,%raft2 /ersion.
.a! 29C 2012 /1.1 .inor up%ates to correct misspellings an% clarif! wor%ing after
fee%4ac9 from AP& -est Practices Tas9 force.
Who Should Read This Document
T#is 4est,practices %ocument is inten%e% for %e/elopers w#o are intereste% in creating R($Tful "e4
ser/ices t#at pro/i%e #ig# relia4ilit! an% consistenc! across multiple ser/ice suites. -! following t#ese
gui%elinesC ser/ices are well positione% for rapi%C wi%esprea%C pu4lic a%option 4! 4ot# internal an%
e@ternal clients.
T#e gui%elines in t#is %ocument are also appropriate for support engineers w#ere t#e! %esire to ser/ices
%e/elope% using t#ese 4est practices. "#ile t#eir concerns ma! 4e focuse% on cac#ing practicesC pro@!
rulesC monitoringC securit! an% suc#C t#is %ocument ma! 4e useful as an o/erarc#ing ser/ice
%ocumentation gui%e of sorts.
A%%itionall!C management personnel ma! 4enefit from t#ese gui%elines 4! en%ea/oring to un%erstan%
t#e effort reDuire% to create ser/ices t#at are pu4licl! consuma4le an% offer #ig# le/els of consistenc!
across t#eir ser/ice suites.
Introduction
T#ere are numerous resources on 4est practices for creating R($Tful we4 ser/ices 0see t#e Resources
section at t#e en% of t#is %ocument2. .an! of t#e a/aila4le resources are conflictingC %epen%ing on
w#en t#e! were written. PlusC rea%ing an% compre#en%ing se/eral 4oo9s on t#e su4Eect in or%er to
implement ser/ices FtomorrowG is not %oa4le. &n or%er to facilitate t#e Duic9 upta9e an% un%erstan%ing
of R($Tful conceptsC wit#out reDuiring t#e rea%ing of at least t#ree to fi/e 4oo9s on t#e su4EectC t#is
gui%e is meant to spee% up t#e processHcon%ensing R($T 4est practices an% con/entions into Eust t#e
#ig# points wit# not a lot of %iscussion.
R($T is more a collection of principles t#an it is a set of stan%ar%s. 1t#er t#an its o/er,arc#ing si@
constraints not#ing is %ictate%. T#ere are I4est practicesI an% %e,facto stan%ar%s 4ut t#ose are
constantl! e/ol/ingHwit# religious 4attles waging continuousl!.
Designe% to 4e 4riefC t#is %ocument pro/i%es recommen%ations an% some coo94oo9,st!le %iscussion on
man! of t#e common Duestions aroun% R($T an% pro/i%es some s#ort 4ac9groun% information to offer
support for effecti/e creation of real,worl%C pro%uction,rea%!C consistent R($Tful ser/ices. T#is
%ocument aggregates information a/aila4le in ot#er sourcesC a%apting it wit# e@perience gaine% t#roug#
#ar% 9noc9s.
T#ere is still consi%era4le %e4ate as to w#et#er R($T is 4etter t#an $1AP 0an% /ice /ersa2C an% per#aps
t#ere are still reasons to create $1AP ser/ices. "#ile touc#ing on $1APC t#is %ocument wonBt spen% a
lot of time %iscussing t#e relati/e merits. &nstea%C 4ecause tec#nolog! an% t#e in%ustr! marc#es onC we
will procee% wit# t#e assumption t#at le/eraging R($T is t#e current 4est practice for "e4 ser/ice
creation.
T#e first section offers an o/er/iew of w#at R($T isC its constraintsC an% w#at ma9es it uniDue. T#e
secon% section supplies some Duic9 tips as little remin%ers of R($T ser/ice concepts. 7ater sections go
more in %ept# to pro/i%e t#e "e4 ser/ice creator more support an% %iscussion aroun% t#e nitt!,gritt!
%etails of creating #ig#,Dualit! R($T ser/ices capa4le of 4eing pu4licl! e@pose% in a pro%uction
en/ironment.
What is REST?
T#e R($T arc#itectural st!le %escri4es si@ constraints. T#ese constraintsC applie% to t#e arc#itectureC
were originall! communicate% 4! Ro! >iel%ing in #is %octoral %issertation 0see
#ttpJ//www.ics.uci.e%u/Kfiel%ing/pu4s/%issertation/restLarc#Lst!le.#tm2 an% %efines t#e 4asis of
R($Tful,st!le.
T#e si@ constraints areJ
*niform &nterface
$tateless
3ac#ea4le
3lient,$er/er
7a!ere% $!stem
3o%e on Deman%
05/29/12 www.RestApiTutorial.com Page ' of 34
A more %etaile% %iscussion of t#e constraints followsJ
Uniform Interface
T#e uniform interface constraint %efines t#e interface 4etween clients an% ser/ers. &t simplifies an%
%ecouples t#e arc#itectureC w#ic# ena4les eac# part to e/ol/e in%epen%entl!. T#e four gui%ing
principles of t#e uniform interface areJ
Resource-Based
&n%i/i%ual resources are i%entifie% in reDuests using *R&s as resource i%entifiers. T#e resources
t#emsel/es are conceptuall! separate from t#e representations t#at are returne% to t#e client. >or
e@ampleC t#e ser/er %oes not sen% its %ata4aseC 4ut rat#erC some T.7C <.7 or =$1; t#at represents
some %ata4ase recor%s e@presse%C for instanceC in >innis# an% enco%e% in *T>,5C %epen%ing on t#e
%etails of t#e reDuest an% t#e ser/er implementation.
Maniulation of Resources Throu!h Reresentations
"#en a client #ol%s a representation of a resourceC inclu%ing an! meta%ata attac#e%C it #as enoug#
information to mo%if! or %elete t#e resource on t#e ser/erC pro/i%e% it #as permission to %o so.
Self-descriti"e Messa!es
(ac# message inclu%es enoug# information to %escri4e #ow to process t#e message. >or e@ampleC
w#ic# parser to in/o9e ma! 4e specifie% 4! an &nternet me%ia t!pe 0pre/iousl! 9nown as a .&.(
t!pe2. Responses also e@plicitl! in%icate t#eir cac#e,a4ilit!.
Hyermedia as the En!ine of #lication State $H#TE%#S&
3lients %eli/er state /ia 4o%! contentsC Duer!,string parametersC reDuest #ea%ers an% t#e reDueste% *R&
0t#e resource name2. $er/ices %eli/er state to clients /ia 4o%! contentC response co%esC an% response
#ea%ers. T#is is tec#nicall! referre%,to as #!perme%ia 0or #!perlin9s wit#in #!perte@t2.
Asi%e from t#e %escription a4o/eC AT(1$ also means t#atC w#ere necessar!C lin9s are containe% in
t#e returne% 4o%! 0or #ea%ers2 to suppl! t#e *R& for retrie/al of t#e o4Eect itself or relate% o4Eects.
"eBll tal9 a4out t#is in more %etail later.
T#e uniform interface t#at an! R($T ser/ices must pro/i%e is fun%amental to its %esign.
Stateless
As R($T is an acron!m for REpresentational State TransferC statelessness is 9e!. (ssentiall!C w#at
t#is means is t#at t#e necessar! state to #an%le t#e reDuest is containe% wit#in t#e reDuest itselfC
w#et#er as part of t#e *R&C Duer!,string parametersC 4o%!C or #ea%ers. T#e *R& uniDuel! i%entifies t#e
resource an% t#e 4o%! contains t#e state 0or state c#ange2 of t#at resource. T#en after t#e ser/er %oes
itBs processingC t#e appropriate stateC or t#e piece0s2 of state t#at matterC are communicate% 4ac9 to t#e
client /ia #ea%ersC status an% response 4o%!.
05/29/12 www.RestApiTutorial.com Page + of 34
.ost of us w#o #a/e 4een in t#e in%ustr! for a w#ile are accustome% to programming wit#in a
container w#ic# pro/i%es us wit# t#e concept of FsessionG w#ic# maintains state across multiple TTP
reDuests. &n R($TC t#e client must inclu%e all information for t#e ser/er to fulfill t#e reDuestC resen%ing
state as necessar! if t#at state must span multiple reDuests. $tatelessness ena4les greater scala4ilit!
since t#e ser/er %oes not #a/e to maintainC up%ate or communicate t#at session state. A%%itionall!C loa%
4alancers %onBt #a/e to worr! a4out session affinit! for stateless s!stems.
$o w#atBs t#e %ifference 4etween state an% a resource) $tateC or application stateC is t#at w#ic# t#e
ser/er cares a4out to fulfill a reDuestH%ata necessar! for t#e current session or reDuest. A resourceC or
resource stateC is t#e %ata t#at %efines t#e resource representationHt#e %ata store% in t#e %ata4aseC for
instance. 3onsi%er application state to 4e %ata t#at coul% /ar! 4! clientC an% per reDuest. Resource
state, on t#e ot#er #an%C is constant across e/er! client w#o reDuests it.
(/er #a% 4ac9,4utton issues wit# a we4 application w#ere it went A"17 at a certain point 4ecause it
e@pecte% !ou to %o t#ings in a certain or%er) T#atBs 4ecause it /iolate% t#e statelessness principle.
T#ere are cases t#at %onBt #onor t#e statelessness principleC suc# as t#ree,legge% 1Aut#C AP& call rate
limitingC etc. owe/erC ma9e e/er! effort to ensure t#at application state %oesnBt span multiple reDuests
of !our ser/ice0s2.
Cacheable
As on t#e "orl% "i%e "e4C clients can cac#e responses. Responses must t#ereforeC implicitl! or
e@plicitl!C %efine t#emsel/es as cac#ea4leC or notC to pre/ent clients reusing stale or inappropriate %ata
in response to furt#er reDuests. "ell,manage% cac#ing partiall! or completel! eliminates some client6
ser/er interactionsC furt#er impro/ing scala4ilit! an% performance.
Clientserver
T#e uniform interface separates clients from ser/ers. T#is separation of concerns means t#atC for
e@ampleC clients are not concerne% wit# %ata storageC w#ic# remains internal to eac# ser/erC so t#at t#e
porta4ilit! of client co%e is impro/e%. $er/ers are not concerne% wit# t#e user interface or user stateC so
t#at ser/ers can 4e simpler an% more scala4le. $er/ers an% clients ma! also 4e replace% an% %e/elope%
in%epen%entl!C as long as t#e interface is not altere%.
Layered system
A client cannot or%inaril! tell w#et#er it is connecte% %irectl! to t#e en% ser/erC or to an interme%iar!
along t#e wa!. &nterme%iar! ser/ers ma! impro/e s!stem scala4ilit! 4! ena4ling loa%,4alancing an% 4!
pro/i%ing s#are% cac#es. 7a!ers ma! also enforce securit! policies.
Code on demand (optional)
$er/ers are a4le to temporaril! e@ten% or customiAe t#e functionalit! of a client 4! transferring logic to
it t#at it can e@ecute. (@amples of t#is ma! inclu%e compile% components suc# as =a/a applets an%
client,si%e scripts suc# as =a/a$cript.
3ompl!ing wit# t#ese constraintsC an% t#us conforming to t#e R($T arc#itectural st!leC will ena4le an!
9in% of %istri4ute% #!perme%ia s!stem to #a/e %esira4le emergent propertiesC suc# as performanceC
scala4ilit!C simplicit!C mo%ifia4ilit!C /isi4ilit!C porta4ilit! an% relia4ilit!.
;1T(J T#e onl! optional constraint of R($T arc#itecture is code on demand. &f a ser/ice /iolates an!
ot#er constraintC it cannot strictl! 4e referre% to as R($Tful.
REST 'uic( Tis
"#et#er itBs tec#nicall! R($Tful or not 0accor%ing to t#e si@ constraints mentione% a4o/e2C #ere are a
few recommen%e% R($T,li9e concepts t#at will result in 4etterC more usa4le ser/icesJ
Use HTTP Verbs to ean Somethin!
An! AP& consumer is capa4le of sen%ing ?(TC P1$TC P*TC an% D(7(T( /er4sC an% t#e! greatl!
en#ance t#e clarit! of w#at a gi/en reDuest %oes. AlsoC ?(T reDuests must not c#ange an! un%erl!ing
resource %ata. .easurements an% trac9ing ma! still occurC w#ic# up%ates %ataC 4ut not resource %ata
i%entifie% 4! t#e *R&.
Sensible "eso#rce $ames
a/ing sensi4le resource names or pat#s 0e.g.C /posts/23 instea% of /api)t!peMpostsNi%M232 impro/es
t#e clarit! of w#at a gi/en reDuest %oes. *sing *R7 Duer!,string parameters is fantastic for filteringC
4ut not for resource names.
Appropriate resource names pro/i%e conte@t for a ser/ice reDuestC increasing un%erstan%a4ilit! of t#e
ser/ice AP&. Resources are /iewe% #ierarc#icall! /ia t#eir *R& namesC offering consumers a frien%l!C
easil!,un%erstoo% #ierarc#! of resources to le/erage in t#eir applications.
Resource names s#oul% 4e nounsHa/oi% /er4s as resource names. &t ma9es t#ings more clear. *se t#e
TTP met#o%s to specif! t#e /er4 portion of t#e reDuest.
%L and &S'$
>a/or =$1; support as t#e %efaultC 4ut unless t#e costs of offering 4ot# =$1; an% <.7 are staggeringC
offer t#em 4ot#. &%eall!C let consumers switc# 4etween t#em 4! Eust c#anging an e@tension from .@ml
to .Eson. &n a%%itionC for supporting A=A<,st!le user interfacesC a wrappe% response is /er! #elpful.
Pro/i%e a wrappe% responseC eit#er 4! %efault or for separate e@tensionsC suc# as .wEson an% .w@ml to
in%icate t#e client is reDuesting a wrappe% =$1; or <.7 response 0see "rappe% Responses 4elow2.
=$1; in regar%s to a Istan%ar%I #as /er! few reDuirements. An% t#ose reDuirements are onl!
s!ntactical in natureC not a4out content format or la!out. &n ot#er wor%sC t#e =$1; response to a R($T
ser/ice call is /er! muc# part of t#e contractHnot %escri4e% in a stan%ar%. .ore a4out t#e =$1; %ata
format can 4e foun% at #ttpJ//www.Eson.org/.
Regar%ing <.7 use in R($T ser/icesC <.7 stan%ar%s an% con/entions are reall! not in pla! ot#er
t#an to utiliAe s!ntacticall! correct tags an% te@t. &n particularC namespaces are notC nor s#oul% t#e! 4e
use in a R($Tful ser/ice conte@t. <.7 t#at is returne% is more =$1; li9eHsimple an% eas! to rea%C
wit#out t#e sc#ema an% namespace %etails presentHEust %ata an% lin9s. &f it en%s up 4eing more
comple@ t#an t#isC see t#e first paragrap# of t#is tipHt#e cost of <.7 will 4e staggering. &n our
e@perience few consumers uses t#e <.7 responses an!wa!. T#is is t#e last Bno%B 4efore it gets p#ase%
out entirel!.
Create (ine)*rained "eso#rces
"#en starting outC itBs muc# easier to create AP&s t#at mimic t#e un%erl!ing application %omain or
%ata4ase arc#itecture of !our s!stem. (/entuall!C !ouBll want aggregate ser/icesHser/ices t#at utiliAe
multiple un%erl!ing resources to re%uce c#attiness. -ut itBs muc# easier to create larger resources later
from in%i/i%ual resources t#an it is to create fine,graine% or in%i/i%ual resources from larger
aggregates. .a9e it eas! on !ourself an% start wit# smallC easil! %efine% resourcesC pro/i%ing 3R*D
functionalit! on t#ose. Oou can create t#ose use,case,oriente%C c#attiness,re%ucing resources later.
Consider Connectedness
1ne of t#e principles of R($T is connecte%nessH/ia #!perme%ia lin9s. "#ile ser/ices are still useful
wit#out t#emC AP&s 4ecome more self,%escripti/e w#en lin9s are returne% in t#e response. At t#e /er!
leastC a BselfB reference informs clients #ow t#e %ata was or can 4e retrie/e%. A%%itionall!C utiliAe t#e
Location #ea%er to contain a lin9 on resource creation /ia P1$T. >or collections returne% in a response
t#at support paginationC BfirstBC BlastBC Bne@tB an% Bpre/B lin9s at a minimum are /er! #elpful.
Definitions
Idempotence
3ontrar! to #ow it soun%sC ma9e no mista9eC t#is #as no relation to certain areas of %isfunction. >rom
"i9ipe%iaJ
In computer science, the term idempotent is used more comprehensively to describe an
operation that will produce the same results if executed once or multiple times. This may
have a different meaning depending on the context in which it is applied. In the case of
methods or subroutine calls with side effects, for instance, it means that the modified state
remains the same after the first call.
>rom a R($Tful ser/ice stan%pointC for an operation 0or ser/ice call2 to 4e i%empotentC clients can
ma9e t#at same call repeate%l! w#ile pro%ucing t#e same resultHoperating muc# li9e a FsetterG
met#o% in a programming language. &n ot#er wor%sC ma9ing multiple i%entical reDuests #as t#e same
effect as ma9ing a single reDuest. ;ote t#at w#ile i%empotent operations pro%uce t#e same result on t#e
ser/er 0si%e effects2C t#e response itself ma! not 4e t#e same 0e.g. a resourceBs state ma! c#ange
4etween reDuests2.
T#e P*T an% D(7(T( met#o%s are %efine% to 4e i%empotent. owe/erC rea% t#e ca/eat on D(7(T(
in t#e HTTP erbs, !"L"T" section 4elow.
?(TC (ADC 1PT&1;$ an% TRA3( met#o%s are %efine% as i%empotent alsoC since t#e! are %efine% as
safe. Rea% t#e section on safet! 4elow.
Safety
>rom "i9ipe%iaJ
#ome methods $for example, H"%!, &"T, 'PTI'(# and TR%)"* are defined as safe,
which means they are intended only for information retrieval and should not change the
state of the server. In other words, they should not have side effects, beyond relatively
harmless effects such as logging, caching, the serving of banner advertisements or
incrementing a web counter. +a,ing arbitrary &"T re-uests without regard to the context
of the application.s state should therefore be considered safe.
&n s#ortC safet! means t#at calling t#e met#o% %oes not cause si%e effects. 3onseDuentl!C clients can
ma9e safe reDuests repeate%l! wit#out worr! of si%e effects on t#e ser/er. T#is means t#at ser/ices
must a%#ere to t#e safet! %efinitions of ?(TC (ADC 1PT&1;$ an% TRA3( operations. 1t#erwiseC
4esi%es 4eing confusing to ser/ice consumersC it can cause pro4lems for "e4 cac#ingC searc# engines
an% ot#er automate% agentsHma9ing uninten%e% c#anges on t#e ser/er.
-! %efinitionC safe operations are i%empotentC since t#e! pro%uce t#e same result on t#e ser/er.
$afe met#o%s are implemente% as rea%,onl! operations. owe/erC safet! %oes not mean t#at t#e ser/er
must return t#e same response e/er! time.
HTT) *erbs
T#e TTP /er4s comprise a maEor portion of our Funiform interfaceG constraint an% pro/i%e us t#e
action counterpart to t#e noun,4ase% resource. T#e primar! or most,commonl!,use% TTP /er4s 0or
met#o%sC as t#e! are properl! calle%2 are P1$TC ?(TC P*TC an% D(7(T(. T#ese correspon% to createC
rea%C up%ateC an% %elete 0or 3R*D2 operationsC respecti/el!. T#ere are a num4er of ot#er /er4sC tooC
4ut are utiliAe% less freDuentl!. 1f t#ose less,freDuent met#o%sC 1PT&1;$ an% (AD are use% more
often t#an ot#ers.
*+T
T#e TTP ?(T met#o% is use% to retrie/e 0or rea%2 a representation of a resource. &n t#e F#app!G 0or
non,error2 pat#C ?(T returns a representation in <.7 or =$1; an% an TTP response co%e of 200
01P2. &n an error caseC it most often returns a 404 0;1T >1*;D2 or 400 0-AD R(8*($T2.
(@amplesJ
&"T http/00www.example.com0customers012345
&"T http/00www.example.com0customers0123450orders
&"T http/00www.example.com0buc,ets0sample
Accor%ing to t#e %esign of t#e TTP specificationC ?(T 0along wit# (AD2 reDuests are use% onl! to
rea% %ata an% not c#ange it. T#ereforeC w#en use% t#is wa!C t#e! are consi%ere% safe. T#at isC t#e! can
4e calle% wit#out ris9 of %ata mo%ification or corruptionHcalling it once #as t#e same effect as calling
it 10 timesC or none at all. A%%itionall!C ?(T 0an% (AD2 is i%empotentC w#ic# means t#at ma9ing
multiple i%entical reDuests en%s up #a/ing t#e same result as a single reDuest.
Do not e@pose unsafe operations /ia ?(THit s#oul% ne/er mo%if! an! resources on t#e ser/er.
PUT
P*T is most,often utiliAe% for up%ate capa4ilitiesC P*T,ing to a 9nown resource *R& wit# t#e reDuest
reDuest 4o%! containing t#e newl!,up%ate% representation of t#e original resource.
owe/erC P*T can also 4e use% to create a resource in t#e case w#ere t#e resource &D is c#osen 4! t#e
client instea% of 4! t#e ser/er. &n ot#er wor%sC if t#e P*T is to a *R& t#at contains t#e /alue of a non,
e@istent resource &D. AgainC t#e reDuest 4o%! contains a resource representation. .an! feel t#is is
con/olute% an% confusing. 3onseDuentl!C t#is met#o% of creation s#oul% 4e use% sparingl!C if at all.
Alternati/el!C use P1$T to create new resources an% pro/i%e t#e client,%efine% &D in t#e 4o%!
representationHpresuma4l! to a *R& t#at %oesnBt inclu%e t#e &D of t#e resource 0see P'#T 4elow2.
(@amplesJ
P6T http/00www.example.com0customers012345
P6T http/00www.example.com0customers0123450orders0789:5
P6T http/00www.example.com0buc,ets0secret;stuff
1n successful up%ateC return 200 0or 204 if not returning an! content in t#e 4o%!2 from a P*T. &f using
P*T for createC return TTP status 201 on successful creation. A 4o%! in t#e response is optionalH
pro/i%ing one consumes more 4an%wi%t#. &t is not necessar! to return a lin9 /ia a 7ocation #ea%er in
t#e creation case since t#e client alrea%! set t#e resource &D. $ee t#e Return alues section 4elow.
P*T is not a safe operationC in t#at it mo%ifies 0or creates2 state on t#e ser/erC 4ut it is idempotent. &n
ot#er wor%sC if !ou create or up%ate a resource using P*T an% t#en ma9e t#at same call againC t#e
resource is still t#ere an% still #as t#e same state as it %i% wit# t#e first call.
&fC for instanceC calling P*T on a resource increments a counter wit#in t#e resourceC t#e call is no
longer idempotent. $ometimes t#at #appens an% it ma! 4e enoug# to %ocument t#at t#e call is not
idempotent. owe/erC itBs recommen%e% to 9eep P*T reDuests idempotent. &t is strongl!
recommen%e% to use P1$T for non,i%empotent reDuests.
P'ST
T#e P1$T /er4 is most,often utiliAe% for creation of new resources. &n particularC itBs use% to create
subordinate resources. T#at isC su4or%inate to some ot#er 0e.g. parent2 resource. &n ot#er wor%sC w#en
creating a new resourceC P1$T to t#e parent an% t#e ser/ice ta9es care of associating t#e new resource
wit# t#e parentC assigning an &D 0new resource *R&2C etc.
(@amplesJ
P'#T http/00www.example.com0customers
P'#T http/00www.example.com0customers0123450orders
1n successful creationC return TTP status 201C returning a Location #ea%er wit# a lin9 to t#e newl!,
create% resource wit# t#e 201 TTP status.
P1$T is neit#er safe or idempotent. &t is t#erefore recommen%e% for non,i%empotent resource reDuests.
.a9ing two i%entical P1$T reDuests will most,li9el! result in two resources containing t#e same
information.
PUT vs P'ST for Creation
&n s#ortC fa/or using P1$T for resource creation. 1t#erwiseC use P*T w#en t#e client is in c#arge of
%eci%ing w#ic# *R& 0/ia itBs resource name or &D2 t#e new resource will #a/eJ if t#e client 9nows w#at
t#e resulting *R& 0or resource &D2 will 4eC use P*T at t#at *R&. 1t#erwiseC use P1$T w#en t#e ser/er
or ser/ice is in c#arge of %eci%ing t#e *R& for t#e newl!,create% resource. &n ot#er wor%sC w#en t#e
client %oesnBt 0or s#oul%nBt2 9now w#at t#e resulting *R& will 4e 4efore creationC use P1$T to create
t#e new resource.
,+L+T+
D(7(T( is prett! eas! to un%erstan%. &t is use% to %elete a resource i%entifie% 4! a *R&.
(@amplesJ
!"L"T" http/00www.example.com0customers012345
!"L"T" http/00www.example.com0customers0123450orders
!"L"T" http/00www.example.com0buc,ets0sample
1n successful %eletionC return TTP status 200 01P2 along wit# a response 4o%!C per#aps t#e
representation of t#e %elete% item 0often %eman%s too muc# 4an%wi%t#2C or a wrappe% response 0see
Return alues 4elow2. (it#er t#at or return TTP status 204 0;1 31;T(;T2 wit# no response 4o%!.
&n ot#er wor%sC a 204 status wit# no 4o%!C or t#e =$(;D,st!le response an% TTP status 200 are t#e
recommen%e% responses.
TTP,spec,wiseC D(7(T( operations are idempotent. &f !ou D(7(T( a resourceC itBs remo/e%.
Repeate%l! calling D(7(T( on t#at resource en%s up t#e sameJ t#e resource is gone. &f calling
D(7(T( sa!C %ecrements a counter 0wit#in t#e resource2C t#e D(7(T( call is no longer idempotent.
As mentione% pre/iousl!C usage statistics an% measurements ma! 4e up%ate% w#ile still consi%ering t#e
ser/ice i%empotent as long as no resource %ata is c#ange%. *sing P1$T for non,i%empotent resource
reDuests is recommen%e%.
T#ere is a ca/eat a4out D(7(T( i%empotenceC #owe/er. 3alling D(7(T( on a resource a secon% time
will often return a 404 0;1T >1*;D2 since it was alrea%! remo/e% an% t#erefore is no longer
fin%a4le. T#is ma9es D(7(T( operations no longer i%empotentC 4ut is an appropriate compromise if
resources are remo/e% from t#e %ata4ase instea% of 4eing simpl! mar9e% as %elete%.
-elow is a ta4le summariAing recommen%e% return /alues of t#e primar! TTP met#o%s in
com4ination wit# t#e resource *R&sJ
HTTP Verb /customers /customers/{id}
?(T 200 01P2C list of customers. *se paginationC
sorting an% filtering to na/igate 4ig lists.
200 01P2C single customer. 404 0;ot
>oun%2C if &D not foun% or in/ali%.
P*T 404 0;ot >oun%2C unless !ou want to
up%ate/replace e/er! resource in t#e entire
collection.
200 01P2 or 204 0;o 3ontent2. 404
0;ot >oun%2C if &D not foun% or
in/ali%.
P1$T 201 03reate%2C B7ocationB #ea%er wit# lin9 to
/customers/Qi%R containing new &D.
404 0;ot >oun%2.
D(7(T( 404 0;ot >oun%2C unless !ou want to %elete t#e
w#ole collectionHnot often %esira4le.
200 01P2. 404 0;ot >oun%2C if &D
not foun% or in/ali%.
Resource +amin!
&n a%%ition to utiliAing t#e TTP /er4s appropriatel!C resource naming is argua4l! t#e most %e4ate%
an% most important concept to grasp w#en creating an un%erstan%a4leC easil! le/erage% "e4 ser/ice
AP&. "#en resources are name% wellC an AP& is intuiti/e an% eas! to use. Done poorl!C t#at same AP&
can feel 9lutA! an% 4e %ifficult to use an% un%erstan%. -elow are a few tips to get !ou going w#en
creating t#e resource *R&s for !our new AP&.
(ssentiall!C a R($T>ul AP& en%s up 4eing simpl! a collection of *R&sC TTP calls to t#ose *R&s an%
some =$1; an%/or <.7 representations of resourcesC man! of w#ic# will contain relational lin9s.
T#e R($Tful principal of addressability is co/ere% 4! t#e *R&s. (ac# resource #as its own a%%ress or
*R&He/er! interesting piece of information t#e ser/er can pro/i%e is e@pose% as a resource. T#e
constraint of uniform interface is partiall! a%%resse% 4! t#e com4ination of *R&s an% TTP /er4sC an%
using t#em in line wit# t#e stan%ar%s an% con/entions.
&n %eci%ing w#at resources are wit#in !our s!stemC name t#em as nouns as oppose% to /er4s or actions.
&n ot#er wor%sC a R($Tful *R& s#oul% refer to a resource t#at is a thing instea% of referring to an
action. ;ouns #a/e properties as /er4s %o notC Eust anot#er %istinguis#ing factor.
$ome e@ample resources areJ
*sers of t#e s!stem.
3ourses in w#ic# a stu%ent is enrolle%.
A userBs timeline of posts.
T#e users t#at follow anot#er user.
An article a4out #orse4ac9 ri%ing.
(ac# resource in a ser/ice suite will #a/e at least one *R& i%entif!ing it. An% itBs 4est w#en t#at *R&
ma9es sense an% a%eDuatel! %escri4es t#e resource. *R&s s#oul% follow a pre%icta4leC #ierarc#ical
structure to en#ance un%erstan%a4ilit! an%C t#ereforeC usa4ilit!J pre%icta4le in t#e sense t#at t#e!Bre
consistentC #ierarc#ical in t#e sense t#at %ata #as structureHrelations#ips. T#is is not a R($T rule or
constraintC 4ut it en#ances t#e AP&.
R($Tful AP&s are written for consumers. T#e name an% structure of *R&s s#oul% con/e! meaning to
t#ose consumers. &tBs often %ifficult to 9now w#at t#e %ata 4oun%aries s#oul% 4eC 4ut wit#
un%erstan%ing of !our %ataC !ou most,li9el! are eDuippe% to ta9e a sta4 an% w#at ma9es sense to return
as a representation to !our clients. Design for !our clientsC not for !our %ata.
7etBs sa! weBre %escri4ing an or%er s!stem wit# customersC or%ersC line itemsC pro%uctsC etc. 3onsi%er
t#e *R&s in/ol/e% in %escri4ing t#e resources in t#is ser/ice suiteJ
"eso#rce U"I +-amples
To insert 0create2 a new customer in t#e s!stemC we mig#t useJ
To rea% a customer wit# 3ustomer &DS 33245J
T#e same *R& woul% 4e use% for P*T an% D(7(T(C to up%ate an% %eleteC respecti/el!.
ere are propose% *R&s for pro%uctsJ
P'#T http/00www.example.com0products
for creating a new pro%uct.
&"T<P6T<!"L"T" http/00www.example.com0products0::432
for rea%ingC up%atingC %eleting pro%uct ''432C respecti/el!.
;owC #ere is w#ere it gets fun... "#at a4out creating a new or%er for a customer)
1ne option mig#t 4eJ
P'#T http/00www.example.com0orders
An% t#at coul% wor9 to create an or%erC 4ut itBs argua4l! outsi%e t#e conte@t of a customer.
-ecause we want to create an or%er for a customer 0note t#e relations#ip2C t#is *R& per#aps is not as
intuiti/e as it coul% 4e. &t coul% 4e argue% t#at t#e following *R& woul% offer 4etter clarit!J
P'#T http/00www.example.com0customers0332450orders
;ow we 9now weBre creating an or%er for customer &DS 33245.
;ow w#at woul% t#e following return)
&"T http/00www.example.com0customers0332450orders
Pro4a4l! a list of or%ers t#at customer S33245 #as create% or owns. ;oteJ we ma! c#oose to not
support D(7(T( or P*T for t#at url since itBs operating on a collection.
;owC to continue t#e #ierarc#ical conceptC w#at a4out t#e following *R&)
P'#T http/00www.example.com0customers0332450orders089:70lineitems
T#at mig#t a%% a line item to or%er S5+'9 0w#ic# is for customer S332452. Rig#tT ?(T for t#at *R&
mig#t return all t#e line items for t#at or%er. owe/erC if line items %onBt ma9e sense onl! in customer
conte@t or also ma9e sense outsi%e t#e conte@t of a customerC we woul% offer a P'#T
www.example.com0orders089:70lineitems *R&.
Along t#ose linesC 4ecause t#ere ma! 4e multiple *R&s for a gi/en resourceC we mig#t also offer a &"T
http/00www.example.com0orders089:7 *R& t#at supports retrie/ing an or%er 4! num4er wit#out #a/ing
to 9now t#e customer num4er.
To go one la!er %eeper in t#e #ierarc#!J
&"T http/00www.example.com0customers0332450orders089:70lineitems01
.ig#t return onl! t#e first line item in t#at same or%er.
-! now !ou can see #ow t#e #ierarc#! concept wor9s. T#ere arenBt an! #ar% an% fast rulesC onl! ma9e
sure t#e impose% structure ma9es sense to consumers of !our ser/ices. As wit# e/er!t#ing in t#e craft
of $oftware De/elopmentC naming is critical to success.
7oo9 at some wi%el! use% AP&s to get t#e #ang of t#is an% le/erage t#e intuition of !our teammates to
refine !our AP& resource *R&s. $ome e@ample AP&s areJ
TwitterJ #ttpsJ//%e/.twitter.com/%ocs/api
>ace4oo9J #ttpJ//%e/elopers.face4oo9.com/%ocs/reference/api/
7in9e%&nJ #ttpsJ//%e/eloper.lin9e%in.com/apis
"eso#rce $amin! .nti)Patterns
"#ile weB/e %iscusse% some e@amples of appropriate resource namesC sometimes itBs informati/e to see
some anti,patterns. -elow are some e@amples of poor R($Tful resource *R&s seen in t#e Fwil%.G
T#ese are e@amples of w#at not to %oT
>irst upC often ser/ices use a single *R& to specif! t#e ser/ice interfaceC using Duer!,string parameters
to specif! t#e reDueste% operation an%/or TTP /er4. >or e@ample to up%ate customer wit# &D 12345C
t#e reDuest for a =$1; 4o%! mig#t 4eJ
&"T http/00api.example.com0services=op>update;customer?id>12345?format>@son
-! nowC !ouBre a4o/e %oing t#is. (/en t#oug# t#e Bser/icesB *R7 no%e is a nounC t#is *R7 is not self,
%escripti/e as t#e *R& #ierarc#! is t#e same for all reDuests. PlusC it uses ?(T as t#e TTP /er4 e/en
t#oug# weBre performing an up%ate. T#is is counter,intuiti/e an% is painful 0e/en %angerous2 to use as
a client.
ereBs anot#er e@ample following t#e same operation of up%ating a customerJ
&"T http/00api.example.com0update;customer012345
An% its e/il twinJ
&"T http/00api.example.com0customers0123450update
OouBll see t#is one a lot as !ou /isit ot#er %e/eloperBs ser/ice suites. ;ote t#at t#e %e/eloper is
attempting to create R($Tful resource names an% #as ma%e some progress. -ut !ouBre 4etter t#an t#is
Ha4le to i%entif! t#e /er4 p#rase in t#e *R7. ;otice t#at we %onBt nee% to use t#e Bup%ateB /er4 p#rase
in t#e *R7 4ecause we can rel! on t#e TTP /er4 to inform t#at operation. =ust to clarif!C t#e
following resource *R7 is re%un%antJ
P6T http/00api.example.com0customers0123450update
"it# 4ot# P*T an% Bup%ateB in t#e reDuestC weBre offering to confuse our ser/ice consumersT &s Bup%ateB
t#e resource) $oC weB/e spent some time 4eating t#e #orse at t#is point. &Bm certain !ou un%erstan%...
Pl#rali/ation
7etBs tal9 a4out t#e %e4ate 4etween t#e pluraliAers an% t#e FsingulariAersG... a/enBt #ear% of t#at
%e4ate) &t does e@ist. (ssentiall!C it 4oils %own to t#is Duestion...
$#oul% *R& no%es in !our #ierarc#! 4e name% using singular or plural nouns) >or e@ampleC s#oul%
!our *R& for retrie/ing a representation of a customer resource loo9 li9e t#isJ
&"T http/00www.example.com0customer033245
orJ
05/29/12 www.RestApiTutorial.com Page 1' of 34
T#ere are goo% arguments on 4ot# si%esC 4ut t#e commonl!,accepte% practice is to always use plurals
in node names to 9eep !our AP& *R&s consistent across all TTP met#o%s. T#e reasoning is 4ase% on
t#e concept t#at customers are a collection wit#in t#e ser/ice suite an% t#e &D 0e.g. 332452 refers to one
of t#ose customers in t#e collection.
*sing t#is ruleC an e@ample multi,no%e *R& using pluraliAation woul% loo9 li9e 0emp#asis a%%e%2J
&"T http/00www.example.com0customers0332450orders089:70lineitems01
wit# BcustomersBC Bor%ersBC an% BlineitemsB *R& no%es all 4eing t#eir plural forms.
T#is implies t#at !ou onl! reall! nee% two 4ase *R7s for eac# root resource. 1ne for creation of t#e
resource wit#in a collection an% t#e secon% for rea%ingC up%ating an% %eleting t#e resource 4! its
i%entifier. >or e@ample t#e creation caseC using customers as t#e e@ampleC is #an%le% 4! t#e following
*R7J
An% t#e rea%C up%ate an% %elete cases are #an%le% 4! t#e followingJ
&"T<P6T<!"L"T" http/00www.example.com0customers0AidB
As mentione% earlierC t#ere ma! 4e multiple *R&s for a gi/en resourceC 4ut as a minimum full 3R*D
capa4ilities are aptl! #an%le% wit# two simple *R&s.
Oou as9 if t#ere is a case w#ere pluraliAation %oesnBt ma9e sense. "ellC !esC in fact t#ere is. "#en
t#ere isnBt a collection concept in pla!. &n ot#er wor%sC itBs accepta4le to use a singulariAe% resource
name w#en t#ere can onl! 4e one of t#e resourceHitBs a singleton resource. >or e@ampleC if t#ere was
a singleC o/erarc#ing configuration resourceC !ou mig#t use a singulariAe% noun to represent t#atJ
&"T<P6T<!"L"T" http/00www.example.com0configuration
;ote t#e lac9 of a configuration &D an% usage of P1$T /er4. An% sa! t#at t#ere was onl! one
configuration per customerC t#en t#e *R7 mig#t 4eJ
&"T<P6T<!"L"T" http/00www.example.com0customers0123450configuration
AgainC no &D for t#e configuration an% no P1$T /er4 usage. Alt#oug#C &Bm sure t#at in 4ot# of t#ese
cases P1$T usage mig#t 4e argue% to 4e /ali%. "ell... 1P.
Returnin! Reresentations
As mentione% earlierC it is %esira4le for a ser/ice to support multiple representations of resourcesC
inclu%ing =$1; an% <.7C as well as wrappe% =$1; an% <.7. As t#e %efault representationC t#e
recommen%ation is =$1;C 4ut ser/ices s#oul% allow clients to specif! alternati/e representations.
>or a client to reDuest a representation formatC t#ere is a Duestion aroun% w#et#er to use t#e Accept
#ea%er a file,e@tension,st!le format specifierC Duer!,string parameterC etc. 1ptimall!C ser/ices woul%
support all of t#ose met#o%s. owe/erC in%ustr! is currentl! con/erging on using a format specifierC
w#ic# loo9s more li9e a file e@tension. T#ereforeC t#e recommen%ation is t#atC at a minimumC ser/ices
support t#e use of file e@tensions suc# as B.EsonBC B.@mlB an% wrappe% optionsC B.wEsonB an% B.w@mlB.
05/29/12 www.RestApiTutorial.com Page 1+ of 34
*sing t#is tec#niDueC t#e representation format is specifie% in t#e *R&C en#ancing /isi4ilit!. >or
e@ampleC &"T http/00www.example.com0customers.xml woul% return t#e list of customer representations
in <.7 format. 7i9ewiseC &"T http/00www.example.com0customers.@son woul% return a =$1;
representation. T#is ma9es t#e ser/ices simple to use from e/en t#e most 4asic client 0suc# as BcurlB2
an% is recommen%e%.
AlsoC ser/ices s#oul% return t#e %efault representation format 0presuma4l! =$1;2 w#en a format
specifier is not inclu%e% on t#e url. >or e@ampleJ
&"T http/00www.example.com0customers012345.@son
-ot# of t#e a4o/e return t#e 12345 customer resource in a =$1; representationC w#ic# is t#e %efault
format for t#is ser/ice.
&"T http/00www.example.com0customers012345.xml
Returns t#e 12345 customer resource in an <.7 representationC if supporte%. &f an <.7 representation
of t#is resource is not supporte% 4! t#is ser/iceC an TTP 404 error s#oul% 4e returne%.
*se of t#e TTP Accept #ea%er is consi%ere% 4! man! to 4e a more elegant approac#C an% is in
9eeping wit# t#e meaning an% intent of t#e TTP specification wit# regar%s to #ow clients notif!
TTP ser/ers of w#ic# content t!pes t#e! support. owe/erC to support 4ot# wrappe% an% unwrappe%
responses from !our ser/icesC in or%er to utiliAe t#e Accept #ea%erC !ou must implement !our own
custom t!pesHsince t#ere are no stan%ar% t!pes for t#ese formats. T#is increases t#e comple@it! of
4ot# clients an% ser/ices greatl!. $ee $ection 14.1 of R>3 2'1'
0#ttpJ//www.w3.org/Protocols/rfc2'1'/rfc2'1',sec14.#tmlSsec14.12 for %etails on t#e Accept #ea%er.
$upporting file,e@tension,st!le format specifiers is simpleC straig#t,forwar%C gets t#e Eo4 %one in t#e
fewest num4er of c#aractersC an% easil! supports scriptingHwit#out #a/ing to le/erage TTP #ea%ers.
&n generalC w#en we tal9 a4out R($T ser/icesC <.7 is largel! irrele/ant. -arel! an!one uses <.7
wit# R($T alt#oug# supporting <.7 is recommen%e%. <.7 stan%ar%s an% con/entions are reall! not
in pla!. &n particularC namespaces are notC nor s#oul% t#e! 4e use in a R($Tful ser/ice conte@t. &t Eust
mu%%ies t#e waters an% ma9es t#ings more complicate%. $o t#e <.7 t#at is returne% is more =$1;
li9eHsimple an% eas! to rea%C wit#out t#e sc#ema an% namespace constraintsHnon,stan%ar% in ot#er
wor%sC 4ut parse,a4le.
"eso#rce ,iscoverability Thro#!h Lin0s (H.T+'.S cont1d)
1ne of t#e gui%ing principals of R($T 0/ia t#e *niform &nterface constraint2 is t#at application state is
communicate% /ia #!perte@t. T#is is often referre% to as !perte@t As T#e (ngine of Application $tate
0AT(1A$2 as mentione% a4o/e in t#e Chat is Rest= $ection.
Accor%ing to Ro! >iel%ingBs 4log 0at #ttpJ//ro!.g4i/.com/untangle%/2005/rest,apis,must,4e,#!perte@t,
%ri/en2C t#e most important part of a R($T interface is its usage of #!perte@t. >urt#erC #e states t#at an
AP& s#oul% 4e usa4le an% un%erstan%a4le gi/en an initial *R& wit#out prior 9nowle%ge or out,of,4an%
information. T#at isC an AP& s#oul% 4e na/iga4le /ia its lin9s to /arious components of t#e %ata.
Returning onl! %ata representations is %iscourage%.
T#is practice is not often followe% 4! current in%ustr! lea%ers in ser/icesC reflecting t#at AT(1A$
usage is #ig#er on t#e maturit! mo%el. 7oo9ing aroun% at man! ser/icesC con/ention is to return more
%ata an% less 0or no2 lin9s. T#is is contrar! to >iel%ingBs R($T constraints. >iel%ing sa!sC F(/er!
a%%ressa4le unit of information carries an a%%ress... 8uer! results are represente% 4! a list of lin9s wit#
summar! informationC not 4! arra!s of o4Eect representations.G
1n t#e ot#er #an%C simpl! returning collections of lin9s can 4e a maEor cause of networ9 c#attiness. &n
t#e real worl%C %epen%ing on reDuirements or use casesC c#attiness of t#e AP& interface is manage% 4!
4alancing #ow muc# Fsummar!G %ata is inclu%e% along wit# t#e relational #!perte@t lin9s in ser/ice
responses.
AlsoC full use of AT(1A$ can increase implementation comple@it! an% impose a significant 4ur%en
on ser/ice clientsC %ecreasing %e/eloper pro%ucti/it! on 4ot# client an% ser/er en%s of t#e eDuation.
3onseDuentl!C it is imperati/e to 4alance #!perlin9ing ser/ice implementations wit# a/aila4le
%e/elopment resources.
A minimal set of #!perlin9ing practices pro/i%es maEor gains in ser/ice usa4ilit!C na/iga4ilit! an%
un%erstan%a4ilit! w#ile minimiAing %e/elopment impact an% re%ucing t#e coupling 4etween client an%
ser/er. T#ese minimal recommen%ations are resources create% /ia P1$T an% for collections returne%
from ?(T reDuestsC wit# a%%itional recommen%ations for pagination casesC w#ic# are %escri4e% 4elow.
Minimal ,in(in! Recommendations
&n create use casesC t#e *R& 0lin92 for t#e newl!,create% resource s#oul% 4e returne% in t#e Location
response #ea%er an% t#e response 4o%! 4e empt!Hor contain onl! t#e &D of t#e newl!,create%
resource.
>or collections of representations 4eing returne% from a ser/iceC eac# representation s#oul% minimall!
carr! a BselfB lin9 propert! in its own lin,s collection. 1t#er lin9s ma! 4e present in t#e returne% as a
separate lin9s collection to facilitate paginationC wit# BfirstBC Bpre/iousBC Bne@tBC BlastB lin9s w#ere
applica4le.
$ee t#e e@amples in t#e Lin, Dormat section 4elow for more information.
,in( -ormat
Regar%ing o/erall lin9 format stan%ar%s it is recommen%e% to a%#ere to some sem4lance of t#e AtomC
AtomPu4C or <lin9 st!le. =$1;,7D is getting some traction tooC 4ut is not wi%el! a%opte% !et 0if it
e/er will 4e2. .ost wi%esprea% in t#e in%ustr! is usage of t#e Atom lin9 st!le wit# a FrelG element an%
an F#refG element t#at contains t#e full *R& for t#e resource wit#out an! aut#entication or Duer!,string
parameters. T#e FrelG elementC can contain t#e stan%ar% /alues IalternateIC Irelate%IC IselfIC
IenclosureIC an% I/iaIC plus FfirstGC FlastGC Fpre/iousGC Fne@tG for pagination lin9s. *se t#em w#ere
t#e! ma9e sense an% a%% !our own w#en nee%e%.
$ome of t#e <.7 Atom format concepts are somew#at irrele/ant for lin9s 4eing represente% in =$1;.
>or instanceC t#e .(T1D propert! is not nee%e% for a R($Tful resource since t#e *R&s are t#e same
for a gi/en resourceC wit# all of t#e TTP met#o%s 4eing supporte% 0for 3R*D 4e#a/ior2,,so listing
t#em in%i/i%uall! is o/er9ill.
7etBs ma9e all t#is tal9 a little more concrete wit# some e@amples. ereBs w#at t#e response woul%
loo9 li9e after creating a new resource wit# a call toJ
P'#T http/00api.example.com0users
An% #ereBs an e@ample set of response #ea%ers wit# t#e Location #ea%er set containing t#e new
resource *R&J
HTTP01.1 2EE 'F
#tatus/ 2EE
)onnection/ close
)ontentGType/ application0@sonH charset>utfG8
Location: http://api.example.com/users/12346
T#e 4o%! is eit#er empt!C or contains a wrappe% response 0see Crapped Responses 4elow2.
ere is an e@ample =$1; response to a ?(T reDuest t#at returns a collection of representations wit#out
pagination in/ol/e%J
AIdataJ/KAIuser;idJ/J42J, InameJ/JLobJ, links/KAIrelJ/JselfJ,
IhrefJ/Jhttp/00api.example.com0users042JBMB, AIuser;idJ/J22J, InameJ/JDran,J, links/
KAIrelJ/JselfJ, IhrefJ/Jhttp/00api.example.com0users022JBMB, AIuser;idJ/J125J, InameJ/ I#allyJ,
links/KAIrelJ/JselfJ, IhrefJ/Jhttp/00api.example.com0users0125JBMBMB
;ote t#e lin9s arra! containing a single reference to FselfG for eac# item in t#e collection. T#is arra!
coul% potentiall! contain ot#er relations#ipsC suc# as c#il%renC parentC etc.
T#e final e@ample is a =$1; response to a ?(T reDuest t#at returns a collection w#ere pagination is
in/ol/e% 0weBre using t#ree items per page2 an% weBre on t#e t#ir% page of t#e collectionJ
AIdataJ/KAIuser;idJ/J42J, InameJ/JLobJ, Ilin,sJ/KAIrelJ/JselfJ,
IhrefJ/Jhttp/00api.example.com0users042JBMB, AIuser;idJ/J22J, InameJ/JDran,J, Ilin,sJ/
KAIrelJ/JselfJ, IhrefJ/Jhttp/00api.example.com0users022JBMB, AIuser;idJ/J125J, InameJ/ I#allyJ,
Ilin,sJ/KAIrelJ/JselfJ, IhrefJ/Jhttp/00api.example.com0users0125JBMBM, links/KAIrelJ/IfirstJ,
IhrefJ/Jhttp/00api.example.com0users=offset>E?limit>3JB, AIrelJ/IlastJ,
IhrefJ/Jhttp/00api.example.com0users=offset>55?limit>3JB, AIrelJ/IpreviousJ,
IhrefJ/Jhttp/00api.example.com0users=offset>3?limit>3JB, AIrelJ/JnextJ,
IhrefJ/Jhttp/00api.example.com0users=offset>7?limit>3JBMB
&n t#is e@ampleC t#e lin9s collection in t#e response is populate% for pagination purposes along wit# t#e
lin9 to FselfG in eac# of t#e items in t#e collection. T#ere coul% 4e a%%itional lin9s #ere relate% to t#e
collection 4ut not relate% to pagination. T#e simple summar! isC t#ere are two places to inclu%e lin9s in
a collection. >or eac# item in t#e collection 0t#ose in t#e data o4EectC w#ic# is t#e collection of
representations reDueste%2C inclu%e a lin9s collection t#atC minimall!C woul% contain a FselfG reference.
T#enC in a separate o4EectC lin,sC inclu%e lin9s t#at appl! to t#e entire collection as applica4leC suc# as
pagination,relate% lin9s.
>or t#e create use caseHcreate /ia P1$TC inclu%e a Location #ea%er wit# a lin9 to t#e newl!,create%
o4Eect.
2rapped "esponses
$er/ices #a/e t#e opportunit! to return 4ot# TTP status co%es along wit# a 4o%! in t#e response. &n
man! =a/a$cript framewor9sC TTP status response co%es are not returne% to t#e en%,%e/eloperC often
pre/enting t#e client from %etermining 4e#a/ior 4ase% on t#at status co%e. A%%itionall!C wit# t#e
m!ria% response co%es in t#e TTP specC often t#ere are onl! a few t#at clients care a4outHfreDuentl!
4oiling %own to BsuccessBC BerrorBC or BfailureB. 3onseDuentl!C it is 4eneficial to wrap responses in a
representation t#at contains information a4out t#e response as well as t#e response itself.
1ne suc# proposal is t#at from 1mniT& 7a4sC t#e so,calle% =$(;D response. .ore information can 4e
foun% at #ttpJ//la4s.omniti.com/la4s/Esen%. Anot#er option is propose% 4! Douglas 3roc9for% an% can
4e rea% a4out at #ttpJ//www.Eson.org/=$1;ReDuest.#tml.
&n practice neit#er of t#ese proposals a%eDuatel! co/ers all cases. -asicall!C current 4est practice is to
wrap regular 0non,=$1;P2 responses wit# t#e following propertiesJ
code 6 contains t#e TTP response status co%e as an integer.
status 6 contains t#e te@tJ FsuccessGC FfailGC or FerrorG. "#ere FfailG is for TTP status
response /alues from 500,599C FerrorG is for statuses 400,499C an% FsuccessG is for e/er!t#ing
else 0e.g. 1<<C 2<< an% 3<< responses2.
message 6 onl! use% for FfailG an% FerrorG statuses to contain t#e error message. >or
internationaliAation 0i15n2 purposesC t#is coul% contain a message num4er or co%eC eit#er alone
or containe% wit#in %elimiters.
data 6 t#at contains t#e response 4o%!. &n t#e case of FerrorG or FfailG statusesC t#is contains t#e
causeC or e@ception name.
A successful response in wrappe% st!le loo9s similar to t#isJ
QIco%eIJ200CIstatusIJIsuccessICI%ataIJ
QIlac9sT1$IJfalseCIin/ali%3re%entialsIJfalseCIaut#To9enIJI4ee'534aa2a3332c3c5'02'%IRR
An e@ample error response in wrappe% st!le loo9s li9e t#isJ
ANcodeN/4E1,NstatusN/NerrorN,NmessageN/Nto,en is invalidN,NdataN/N6nauthoriOed"xceptionNB
&n <.7C t#ese two wrappe% responses woul% correspon% toJ
UresponseV
Uco%eV200U/co%eV
UstatusVsuccessU/statusV
U%ata classMIAut#enticationResultIV
Ulac9sT1$VfalseU/lac9sT1$V
Uin/ali%3re%entialsVfalseU/in/ali%3re%entialsV
Uaut#To9enV1.0Wi%mWi%mW4ee'534aa2a3332c3c5'02'%U/aut#To9enV
U/%ataV
U/responseV
An%J
UresponseV
Uco%eV401U/co%eV
UstatusVerrorU/statusV
UmessageVto9en is in/ali%U/messageV
U%ata classMIstringIV*naut#oriAe%(@ceptionU/%ataV
U/responseV
Handlin! Cross),omain Iss#es
"eB/e all #ear% a4out wor9ing aroun% t#e 4rowserBs same origin polic! or common,source reDuirement.
&n ot#er wor%sC t#e 4rowser can onl! ma9e reDuests to t#e site itBs currentl! %ispla!ing. >or e@ampleC if
t#e site currentl! 4eing %ispla!e% is www."xample1.comC t#en t#at site cannot perform a reDuest against
www."xample2.com. 14/iousl!C t#is impacts #ow sites access ser/ices.
Presentl!C t#ere are two wi%el!,accepte% met#o%s to support cross,%omain reDuestsJ =$1;P an% 3ross,
1rigin Resource $#aring 031R$2. =$1;P or I=$1; wit# pa%%ingI is a usage pattern t#at pro/i%es a
met#o% to reDuest %ata from a ser/er in a %ifferent %omain. &t wor9s 4! t#e ser/ice returning ar4itrar!
=a/a$cript co%e instea% of =$1;. T#ese responses are e/aluate% 4! t#e =a/a$cript interpreterC not
parse% 4! a =$1; parser. 31R$C on t#e ot#er #an%C is a we4 4rowser tec#nolog! specificationC w#ic#
%efines wa!s for a we4 ser/er to allow its resources to 4e accesse% 4! a we4 page from a %ifferent
%omain. &t is seen as a mo%ern alternati/e to =$1;P an% is supporte% 4! all mo%ern 4rowsers.
T#ereforeC =$1;P is not recommen%e%. 3#oose 31R$ w#ene/er an% w#ere/er possi4le.
Suortin! C%RS
&mplementing 31R$ on a ser/er is as simple as sen%ing an a%%itional TTP #ea%er in t#e responseC for
e@ampleJ
Access,3ontrol,Allow,1riginJ X
An access origin of BXB s#oul% onl! 4e set if t#e %ata is meant for public consumption. &n most cases
t#e Access,3ontrol,Allow,1rigin #ea%er s#oul% specif! !ic! domains s#oul% 4e a4le to initiate a
31R$ reDuest. 1nl! *R7s t#at nee% to 4e accesse% cross,%omain s#oul% #a/e t#e 31R$ #ea%er set.
%ccessG)ontrolG%llowG'rigin/ http/00example.com/8E8E http/00foo.example.com
Allow onl! truste% %omains in Access,3ontrol,Allow,1rigin #ea%er.
%ccessG)ontrolG%llowG)redentials/ true
*se t#is #ea%er onl! w#en necessar! as it will sen% t#e coo9ies/sessions if t#e user is logge% into t#e
application.
T#ese #ea%ers can 4e configure% /ia t#e "e4 ser/erC pro@! or sent from t#e ser/ice itself.
&mplementing it wit#in t#e ser/ices is not recommen%e% as itBs not fle@i4le. &nstea%C use t#e secon%
formC a space %elimite% list of appropriate %omains configure% on !our "e4 ser/er. .ore a4out 31R$
can 4e foun% atJ #ttpJ//ena4le,cors.org/.
Suortin! .S%+)
=$1;P gets aroun% t#e 4rowser limitation 4! utiliAing ?(T reDuests to perform all ser/ice calls. &n
essenceC t#e reDuester a%%s a Duer!,string parameter 0e.g. EsonpMGEsonpLcall4ac9G2 to t#e reDuestC
w#ere t#e /alue of t#e FEsonpG parameter is t#e name of a Ea/ascript function t#at will 4e calle% w#en
t#e response is returne%.
T#ere se/ere limitations to t#e functionalit! ena4le% 4! =$1;PC since ?(T reDuests %o not contain a
reDuest 4o%! an%C t#ereforeC information must 4e passe% /ia Duer!,string parameters. AlsoC to support
P*TC P1$T an% D(7(T( operationsC t#e effecti/e TTP met#o% must also 4e passe% as a Duer!,string
argumentC suc# as Lmet#o%MP1$T. Tunneling t#e TTP met#o% li9e t#is is not recommen%e% an% can
open ser/ices up to securit! ris9s.
=$1;P wor9s on legac! 4rowsers w#ic# preclu%e 31R$ supportC 4ut affects #ow ser/ices are 4uilt if
t#e!Bre going to support it. Alternati/el!C =$1;P can 4e implemente% /ia a pro@!. 1/erallC =$1;P is
4eing %e,emp#asiAe% in fa/or of 31R$. >a/or 31R$ w#ene/er possi4le.
To support =$1;P on t#e ser/er si%eC w#en t#e =$1;P Duer!,string parameter is passe% inC t#e
response must 4e manipulate% a 4it as followsJ
1. T#e response 4o%! must 4e wrappe% as t#e parameter to t#e gi/en Ea/ascript function in t#e
Esonp parameter 0e.g. EsonpLcall4ac90FU=$1; response 4o%!VG22.
2. Alwa!s return TTP status 200 01P2 an% return t#e actual status as part of t#e =$1; response.
A%%itionall!C itBs also often necessar! to inclu%e #ea%ers as part of t#e response 4o%!. T#is ena4les t#e
=$1;P call4ac9 met#o% to ma9e %ecisions on response #an%ling 4ase% on t#e response 4o%! since itBs
not pri/! to t#e information in response #ea%ers an% status.
An e@ample error response following t#e a4o/e wrappe% response recommen%ations is as follows
0noteJ TTP response status is 2002J
@sonp;callbac,$IA.code./.4E4., .status./.error.,.headers./KM,.message./.resource PQR not
found.,.data./.(otDound"xception.BJ*
A successful creation response loo9s li9e t#is 0still wit# an TTP response status of 2002J
@sonp;callbac,$IA.code./.2E1., .status./.error.,.headers./
KA.Location./.http/00www.example.com0customers012345.BM,.data./.12345.BJ*
'ueryin!/ -ilterin! and )a!ination
>or large %ata setsC limiting t#e amount of %ata returne% is important from a 4an%,wi%t# stan%point.
-ut itBs also important from a *& processing stan%point as a *& often can onl! %ispla! a small portion of
a #uge %ata set. &n cases w#ere t#e %ataset grows in%efinitel!C itBs #elpful to limit t#e amount of %ata
returne% 4! %efault. >or instanceC in t#e case of Twitter returning a personBs tweets 0/ia t#eir #ome
timeline2C it returns up to 20 items unless ot#erwise specifie% in t#e reDuest an% e/en t#en will return a
ma@imum of 200.
Asi%e from limiting t#e amount of %ata returne%C we also nee% to consi%er #ow to FpageG or scroll
t#roug# t#at large %ata set if more t#an t#at first su4set nee%s retrie/al. T#is is referre% to as pagination
Hcreating FpagesG of %ataC returning 9nown sections of a larger list an% 4eing a4le to page Fforwar%G
an% F4ac9war%G t#roug# t#at large %ata set. A%%itionall!C we ma! want to specif! t#e fiel%s or
properties of a resource to 4e inclu%e% in t#e responseC t#ere4! limiting t#e amount of %ata t#at comes
4ac9 an% we e/entuall! want to Duer! for specific /alues an%/ or sort t#e returne% %ata.
T#ere are com4inations of two primar! wa!s to limit Duer! results an% perform pagination. >irstC t#e
in%e@ing sc#eme is eit#er page,oriente% or item,oriente%. &n ot#er wor%sC incoming reDuests will
specif! w#ere to 4egin returning %ata wit# eit#er a FpageG num4erC specif!ing a num4er of items per
pageC or specif! a first an% last item num4er %irectl! 0in a range2 to return. &n ot#er wor%s t#e two
options areC Fgi/e me page 5 assuming 20 items per pageG or Fgi/e me items 100 t#roug# 120.G
$er/ice pro/i%ers are split on #ow t#is s#oul% wor9. owe/erC some *& toolsC suc# as t#e DoEo =$1;
Datastore o4EectC c#ooses to mimic t#e TTP specifications use of 4!te ranges. &tBs /er! #elpful if !our
ser/ices support t#at rig#t out of t#e 4o@ so no translation is necessar! 4etween !our *& tool9it an%
4ac9,en% ser/ices.
T#e recommen%ations 4elow support 4ot# t#e DoEo mo%el for paginationC w#ic# is to specif! t#e range
of items 4eing reDueste% using t#e Range #ea%erC an% utiliAation of Duer!,string parameters. -!
supporting 4ot#C ser/ices are more fle@i4leHusa4le from 4ot# a%/ance% *& tool9itsC li9e DoEoC as well
as 4! simpleC straig#t,forwar% lin9s an% anc#or tags. &t s#oul%nBt a%% muc# comple@it! to t#e
%e/elopment effort to support 4ot# options. owe/erC if !our ser/ices %onBt support *& functionalit!
%irectl!C consi%er eliminating support for t#e Range #ea%er option.
&tBs important to note t#at Duer!ingC filtering an% pagination are not recommen%e% for all ser/ices. T#is
4e#a/ior is resource specific an% s#oul% not 4e supporte% on all resources 4! %efault. Documentation
for t#e ser/ices an% resources s#oul% mention w#ic# en%,points support t#ese more comple@
capa4ilities.
Limitin! "es#lts
T#e Fgi/e me items 3 t#roug# 55G wa! of reDuesting %ata is more consistent wit# #ow t#e TTP spec
utiliAes t#e Range #ea%er for 4!tes so we use t#at metap#or wit# t#e Range #ea%er. owe/erC t#e
Fstarting wit# item 2 gi/e me a ma@imum of 20 itemsG is easier for #umans to rea%C formulate an%
un%erstan% so we use t#at metap#or in supporting t#e Duer!,string parameters.
As mentione% a4o/eC t#e recommen%ation is to support use of 4ot# t#e TTP Range #ea%er plus Duer!,
string parametersC offset an% limitC in our ser/ices to limit results in responses. ;ote t#atC gi/en support
for 4ot# optionsC t#e Duer!,string parameters s#oul% o/erri%e t#e Range #ea%er.
1ne of t#e first Duestions !our going to as9 isC F"#! are we supporting two metap#ors wit# t#ese
similar functions as t#e num4ers in t#e reDuests will ne/er matc#) &snBt t#at confusing)G *m... T#atBs
two Duestions. "ellC to answer !our DuestionC it ma! 4e confusing. T#e t#ing isC we want to ma9e
t#ings in t#e Duer!,string especiall! clearC easil!,un%erstoo%C #uman rea%a4le an% eas! to construct an%
parse. T#e Range #ea%erC #owe/erC is more mac#ine,4ase% wit# usage %ictate% to us /ia t#e TTP
specification.
&n s#ortC t#e Range #ea%er items /alue must 4e parse%C w#ic# increases t#e comple@it!C plus t#e client
si%e #as to perform some computation in or%er to construct t#e reDuest. *sing t#e in%i/i%ual limit an%
offset parameters are easil!,un%erstoo% an% create%C usuall! wit#out muc# %eman% on t#e #uman
element.
,imitin! "ia the Ran!e Header
"#en a reDuest is ma%e for a range of items using a TTP #ea%er instea% of Duer!,string parametersC
inclu%e a Range #ea%er specif!ing t#e range as followsJ
Range/ items>EG24
;ote t#at items are Aero,4ase% to 4e consistent wit# t#e TTP specification in #ow it uses t#e Range
#ea%er to reDuest 4!tes. &n ot#er wor%sC t#e first item in t#e %ataset woul% 4e reDueste% 4! a 4eginning
range specifier of Aero 002. T#e a4o/e reDuest woul% return t#e first 25 itemsC assuming t#ere were at
least 25 items in t#e %ata set.
1n t#e ser/er si%eC inspect t#e Range #ea%er in t#e reDuest to 9now w#ic# items to return. 1nce a
Range #ea%er is %etermine% to e@istC it can 4e simpl! parse% using a regular e@pression 0e.g.
FitemsM0YY%Z2,0YY%Z2G2 to retrie/e t#e in%i/i%ual range /alues.
,imitin! "ia 'uery-Strin! )arameters
>or t#e Duer!,string alternati/e to t#e Range #ea%erC use parameter names of offset an% limitC w#ere
offset is t#e 4eginning item num4er 0matc#es t#e first %igit in t#e items string for t#e Range #ea%er
a4o/e2 an% limit is t#e ma@imum num4er of items to return. A reDuest using Duer!,string parameters
t#at matc#es t#e e@ample in t#e Range ea%er section a4o/e isJ
&"T http/00api.example.com0resources=offset=!limit=2"
T#e offset /alue is Aero,4ase%C Eust li9e t#e items in t#e Range #ea%er. T#e /alue for limit is t#e
ma@imum num4er of items to return. $er/ices can impose t#eir own %efault an% ma@imum /alues for
limit for w#en itBs not specifie% in t#e Duer! string. -ut please %ocument t#ose Fin/isi4leG settings.
;ote t#at w#en t#e Duer!,string parameters are use%C t#e /alues s#oul% o/erri%e t#ose pro/i%e% in t#e
Range #ea%er.
Ran!e-Based Resonses
>or a range,4ase% reDuestC w#et#er /ia Range TTP #ea%er or Duer!,string parametersC t#e ser/er
s#oul% respon% wit# a )ontentGRange #ea%er to in%icate #ow man! items are 4eing returne% an% #ow
man! total items e@ist !et to 4e retrie/e%J
)ontentGRange/ items EG240::
;ote t#at t#e total items a/aila4le 0e.g. '' in t#is case2 is not Aero,4ase%. enceC reDuesting t#e last
few items in t#is %ata set woul% return a )ontentGRange #ea%er as followsJ
)ontentGRange/ items 4EG:50::
Accor%ing to t#e TTP specificationC it is also /ali% to replace t#e total items a/aila4le 0'' in t#is case2
wit# an asteris9 0FXG2 if t#e num4er of items is un9nown at response timeC or if t#e calculation of t#at
num4er is too e@pensi/e. &n t#is case t#e response #ea%er woul% loo9 li9e t#isJ
)ontentGRange/ items 4EG:50S
owe/erC note t#at DoEo or ot#er *& tools ma! not support t#is notation.
Pa!ination
T#e a4o/e response,limiting sc#emes wor9s for pagination 4! allowing reDuesters to specif! t#e items
wit#in a %ataset in w#ic# t#e!Bre intereste%. *sing t#e a4o/e e@ample w#ere '' total items are
a/aila4leC retrie/ing t#e secon% FpageG of %ata using a page siAe of 25 woul% use a Range #ea%er as
followsJ
Range/ items>25G47
:ia Duer!,string parametersC t#is woul% 4e eDui/alent toJ
&"T ...=offset=2"!limit=2"
"#ereuponC t#e ser/er 0gi/en our e@ample2 woul% return t#e %ataC along wit# a )ontentGRange #ea%er
as followsJ
)ontentGRange/ 25G470::
T#is is wor9s great for most t#ings. owe/erC occasionall! t#ere are cases w#ere item num4ers %onBt
translate %irectl! to rows in t#e %ata set. AlsoC for an e@tremel! acti/e %ata set w#ere new items are
regularl! a%%e% to t#e top of t#e listC apparent Fpaging issuesG wit# w#at loo9 li9e %uplicates can occur.
Date,or%ere% %ata sets are a common case li9e a Twitter fee%. "#ile !ou can still page t#roug# t#e %ata
using item num4ersC sometimes itBs more 4eneficial an% un%erstan%a4le to use an FafterG or F4eforeG
Duer!,string parameterC optionall! in conEunction wit# t#e Range #ea%er 0or Duer!,string parametersC
offset an% limit2.
>or e@ampleC to retrie/e up to 20 remar9s aroun% a gi/en timestampJ
&"T http/00www.example.com0remar,s0home;timeline=after>TtimestampU
Range/ items>EG17
&"T http/00www.example.com0remar,s0home;timeline=before>TtimestampU
Range/ items>EG17
(Dui/alentl!C using Duer!,string parametersJ
&"T http/00www.example.com0remar,s0home;timeline=after>TtimestampU?offset>E?limit>2E
&"T http/00www.example.com0remar,s0home;timeline=before>TtimestampU?offset>E?limit>2E
>or timestamp formatting an% #an%ling in %ifferent casesC please see t#e !ate Handling section 4elow.
&f a ser/ice returns a su4set of %ata 4! %efault or a ma@imum num4er of arguments e/en w#en t#e
reDuester %oes not set a Range #ea%erC #a/e t#e ser/er respon% wit# a )ontentGRange #ea%er to
communicate t#e limit to t#e client. >or e@ampleC in t#e #omeLtimeline e@ample a4o/eC t#at ser/ice
call ma! onl! e/er return 20 items at a time w#et#er t#e reDuester sets t#e Range #ea%er or not. &n t#at
caseC t#e ser/er s#oul% alwa!s respon% wit# content range #ea%er suc# asJ
)ontentGRange/ EG1704125
or )ontentGRange/ EG170S
05/29/12 www.RestApiTutorial.com Page 2' of 34
(ilterin! and Sortin! "es#lts
Anot#er consi%eration for affecting results is t#e act of filtering %ata an%/or or%ering it on t#e ser/erC
retrie/ing a su4set of %ata an%/or in a specifie% or%er. T#ese concepts wor9 in conEunction wit#
pagination an% results,limiting an% utiliAe Duer!,string parametersC filter an% sort respecti/el!C to %o
t#eir magic.
AgainC filtering an% sorting are comple@ operations an% %onBt nee% to 4e supporte% 4! %efault on all
resources. Document t#ose resources t#at offer filtering an% sorting.
-ilterin!
&n t#is caseC filtering is %efine% as re%ucing t#e num4er of results returne% 4! specif!ing some criteria
t#at must 4e met on t#e %ata 4efore it is returne%. >iltering can get Duite comple@ if ser/ices support a
complete set of comparison operators an% comple@ criteria matc#ing. owe/erC it is Duite often
accepta4le to 9eep t#ings sane 4! supporting a simple eDualit!C Bstarts,wit#B or contains comparison.
-efore we get starte% %iscussing w#at goes in t#e filter Duer!,string parameterC itBs important to
un%erstan% w#! a single parameter /s. multiple Duer!,string parameters is use%. -asicall!C it comes
%own to re%ucing t#e possi4ilit! of parameter name clas#es. "eBre alrea%! em4racing t#e use of offsetC
limitC an% sort 0see 4elow2 parameters. T#en t#ereBs @sonp if !ou c#oose to support itC t#e format
specifier an% possi4l! after an% before parameters. An% t#atBs Eust t#e Duer!,string parameters
%iscusse% in t!is %ocument. T#e more parameters we use on t#e Duer!,string t#e more possi4ilities we
#a/e to #a/e name clas#es or o/erlap. *sing a single filter parameter minimiAes t#at.
PlusC itBs easier from t#e ser/er,si%e to %etermine if filtering functionalit! is reDueste% 4! simpl!
c#ec9ing for t#e presence of t#at single filter parameter. AlsoC as comple@it! of !our Duer!ing
reDuirements increasesC t#is single parameter option pro/i%es more fle@i4ilit! in t#e futureHfor
creating !our own full!,functional Duer! s!nta@ 0see 1Data comments 4elow or at
#ttpJ//www.o%ata.org2.
-! em4racing a set of commonC accepte% %elimitersC eDualit! comparison can 4e implemente% in
straig#t,forwar% fas#ion. $etting t#e /alue of t#e filter Duer!,string parameter to a string using t#ose
%elimiters creates a list of name//alue pairs w#ic# can 4e parse% easil! on t#e ser/er,si%e an% utiliAe%
to en#ance %ata4ase Dueries as nee%e%. T#e %elimiters t#at #a/e wor9e% as con/entions are t#e /ertical
4ar 0FWG2 to separate in%i/i%ual filter p#rases an% a %ou4le colon 0FJJG2 to separate t#e names an% /alues.
T#is pro/i%es a uniDue,enoug# set of %elimiters to support t#e maEorit! of use cases an% creates a user,
rea%a4le Duer!,string parameter. A simple e@ample will ser/e to clarif! t#e tec#niDue. $uppose we want
to reDuest users wit# t#e name FTo%%G w#o li/e in Den/er an% #a/e t#e title of F?ran% Poo4a#G. T#e
reDuest *R&C complete wit# Duer!,string mig#t loo9 li9e t#isJ
&"T http/00www.example.com0users=filter>Nname//todd<city//denver<title//grand poobahJ
T#e %elimiter of t#e %ou4le colon 0FJJG2 separates t#e propert! name from t#e comparison /alueC
ena4ling t#e comparison /alue to contain spacesHma9ing it easier to parse t#e %elimiter from t#e /alue
on t#e ser/er.
;ote t#at t#e propert! names in t#e name//alue pairs matc# t#e name of t#e properties t#at woul% 4e
returne% 4! t#e ser/ice in t#e pa!loa%.
05/29/12 www.RestApiTutorial.com Page 2+ of 34
$imple 4ut effecti/e. 3ase sensiti/it! is certainl! up for %e4ate on a case,4!,case 4asisC 4ut in generalC
filtering wor9s 4est w#en case is ignore%. Oou can also offer wil%,car%s as nee%e% using t#e asteris9
0FXG2 as t#e /alue portion of t#e name//alue pair.
>or Dueries t#at reDuire more,t#an simple eDualit! or wil%,car% comparisonsC intro%uction of operators
is necessar!. &n t#is caseC t#e operators t#emsel/es s#oul% 4e part of t#e /alue an% parse% on t#e ser/er
si%eC rat#er t#an part of t#e propert! name. "#en comple@ Duer!,language,st!le functionalit! is
nee%e%C consi%er intro%ucing Duer! concept from t#e 1pen Data Protocol 01Data2 >ilter $!stem 8uer!
1ption specification 0see #ttpJ//www.o%ata.org/%ocumentation/uri,
con/entionsS>ilter$!stem8uer!1ption2.
Sortin!
>or our purposesC sorting is %efine% as %etermining t#e or%er in w#ic# items in a pa!loa% are returne%
from a ser/ice. &n ot#er wor%sC t#e sort or%er of multiple items in a response pa!loa%.
AgainC con/ention #ere sa!s to %o somet#ing simple. T#e recommen%e% approac# is to utiliAe a sort
Duer!,string parameter t#at contains a %elimite% set of propert! names. -e#a/ior isC for eac# propert!
nameC sort in ascen%ing or%erC an% for eac# propert! prefi@e% wit# a %as# 0F,G2 sort in %escen%ing or%er.
$eparate eac# propert! name wit# a /ertical 4ar 0FWG2C w#ic# is consistent wit# t#e separation of t#e
name//alue pairs in filteringC a4o/e.
>or e@ampleC if we want to retrie/e users in or%er of t#eir last name 0ascen%ing2C first name 0ascen%ing2
an% #ire %ate 0%escen%ing2C t#e reDuest mig#t loo9 li9e t#isJ
&"T http/00www.example.com0users=sort>last;name<first;name<Ghire;date
;ote t#at again t#e propert! names matc# t#e name of t#e properties t#at woul% 4e returne% 4! t#e
ser/ice in t#e pa!loa%. A%%itionall!C 4ecause of its comple@it!C offer sorting on a case,4!,case 4asis for
onl! resources t#at nee% it. $mall collections of resources can 4e or%ere% on t#e clientC if nee%e%.
Ser"ice *ersionin!
$er/ices s#oul% 4e /ersione% as earl! as possi4le in t#e %e/elopment c!cle. An! initial pu4lic or
internal release s#oul% 4e /ersione% rig#t out of t#e gate.
As a %e/eloperC itBs easiest to use an AP& w#en t#at AP& is accessi4le /ia simple tools li9e a 4rowserC
4rowser plug,ins or comman%,line tools li9e BcurlB. T#ereforeC in t#e case of /ersioningC t#e concept of
B/isi4ilit!B comes /er! muc# into pla!. T#is means t#at it s#oul% 4e /er! o4/ious to t#e AP& consumer
w#ic# /ersion of t#at AP& t#e! are consuming. 3onseDuentl!C to en#ance t#at /isi4ilit! it is
recommen%e% to place a /ersion num4er %irectl! in resource *R&sC /er! #ig# in t#e *R& no%e
#ierarc#!.
T#is tec#niDue flies in t#e face of muc# aca%emic R($T con/ersations as it %oesnBt em4race t#e 4uilt,in
#ea%er s!stem of t#e TTP specification using etagsC or t#at a new *R& s#oul% 4e a%%e% onl! w#en a
new concept is intro%uce%. >urt#ermoreC anot#er argument against it is t#at resource *R&s arenBt meant
to c#ange o/er timeHw#en somet#ing unrelate% to t#e resourceC li9e a new AP& /ersion comes out.
owe/erC putting t#e /ersion in t#e *R& ma9es t#e AP& easier to useC testC an% /erif! t#at t#e
appropriate resource representation /ersion is 4eing reDueste%. &t coul% also 4e argue% t#at since
returne% /alues are actuall! representationsHnot t#e resource itselfHt#e /ersion num4er reflects a
resource representation appropriatel!. A%%itionall!C man! of t#e F4ig 4o!sG suc# as TwitterC OammerC
>ace4oo9C ?oogleC etc. freDuentl! utiliAe /ersion num4ers in t#eir *R&s.
T#e current recommen%ation is to support /ersioning /ia /ersion num4ers %irectl! in resource *R&s. &t
ma9es t#e /ersion /isi4le an% a /ersione% AP& easier to un%erstan% an% use correctl!.
:ersion num4ers in *R&s s#oul% 4e #ig# in t#e no%e #ierarc#!C prefera4l! as t#e first no%eC for
e@ampleJ api.example.com0v10users or www.example.com0api0v10users.
Date0Time Handlin!
Dates an% timestamps can 4e a real #ea%ac#e if not %ealt wit# appropriatel! an% consistentl!.
TimeAone issues can crop up easil! an% since %ates are Eust strings in =$1; pa!loa%sC parsing is a real
issue if t#e format isnBt 9nownC consistent or specifie%.
&nternall!C ser/ices s#oul% storeC processC cac#eC etc. suc# timestamps in *T3 or ?.T time. T#is
alle/iates timeAone issues wit# 4ot# %ates an% timestamps.
,ate3Time Seriali/ation In 4ody Content
T#ereBs an eas! wa! aroun% all of t#isHalwa!s use t#e same formatC inclu%ing t#e time portion 0along
wit# timeAone information2 in t#e string. &$1 5'01 time point format is a goo% solutionC using t#e
full!,en#ance% format t#at inclu%es #oursC minutesC secon%s an% a %ecimal fraction of secon%s 0e.g.
!!!!,..,%%BTBJmmJss.$$$B[B2. &t is recommen%e% t#at &$1 5'01 4e use% for all %ates represente%
in R($T ser/ice 4o%! content 04ot# reDuests an% responses2.
&nci%entall!C for t#ose %oing =a/a,4ase% ser/icesC t#e DateA%apter= li4rar! easil! parses an% formats
&$15'01 %ates an% time points an% TTP 1.1 #ea%er 0R>3 11232 formatsC wit# its DateA%apterC
&so5'01TimepointA%apter an% ttpea%erTimestampA%apter implementation classesC respecti/el!. &t
can 4e %ownloa%e% at #ttpsJ//git#u4.com/tfre%ric#/DateA%apter=.
>or t#ose creating 4rowser,4ase% *&sC t#e (3.A$cript 5 specification inclu%es parsing an% creating
&$15'01 %ates in =a/a$cript nati/el!C so it s#oul% 4e ma9ing its wa! into all mainstream 4rowsers as
we spea9. &f !ouBre supporting ol%er 4rowsers t#at %onBt nati/el! parse t#ose %atesC a =a/a$cript li4rar!
or fanc! regular e@pression is in or%er. A couple of sample =a/a$cript li4raries t#at can parse an%
pro%uce &$15'01 Timepoints areJ
#ttpJ//momentEs.com/
#ttpJ//www.%ateEs.com/
,ate3Time Seriali/ation In HTTP Headers
"#ile t#e a4o/e recommen%ation wor9s for =$1; an% <.7 content in t#e content of an% TTP
reDuest or responseC t#e TTP specification utiliAes a %ifferent format for TTP #ea%ers. $pecifie% in
R>3 522 w#ic# was up%ate% 4! R>3 1123C t#at format inclu%es /arious %ateC time an% %ate,time
formats. owe/erC it is recommen%e% to alwa!s use a timestamp formatC w#ic# en%s up loo9ing li9e
t#is in !our reDuest #ea%ersJ
$unC 0' ;o/ 1994 05J49J3+ ?.T
*nfortunatel!C it %oesnBt account for a millisecon% or %ecimal fraction of a secon% in its format. T#e
=a/a $impleDate>ormat specifier string isJ I(((C %% ... !!!! JmmJss B?.TBI
Securin! Ser"ices
Aut#entication is t#e act of /erif!ing t#at a gi/en reDuest is from someone 0or some s!stem2 t#at is
9nown to t#e ser/ice an% t#at t#e reDuestor is w#o t#e! sa! t#e! are. "#ile aut#entication is t#e act of
/erif!ing a reDuestor is w#o t#e! sa! t#e! areC aut#oriAation is /erif!ing t#e reDuestor #as permission to
perform t#e reDueste% operation.
(ssentiall!C t#e process goes somet#ing li9e t#isJ
1. 3lient ma9es a reDuestC inclu%ing aut#entication to9en in PG%uthoriOation #ea%er or to,en
Duer!,string parameter in t#e reDuest.
2. $er/ice /erifies presence of t#e aut#oriAation to9enC /ali%ates it 0t#at itBs /ali% an% not e@pire%2
an% parses or loa%s t#e aut#entication principal 4ase% on t#e to9en contents.
3. $er/ice ma9es a call to t#e aut#oriAation ser/ice pro/i%ing aut#entication principalC reDueste%
resource an% reDuire% permission for operation.
4. &f aut#oriAe%C ser/ice continues wit# normal processing.
S3 a4o/e coul% 4e e@pensi/eC 4ut assuming a cac#ea4le access,control list 0A372C it is concei/a4le to
create an aut#oriAation client t#at cac#es t#e most,recent A37s to /ali%ate locall! 4efore ma9ing
remote calls.
.#thentication
3urrent 4est practice is to use 1Aut# for aut#entication. 1Aut#2 is #ig#l! recommen%e%C 4ut is still in
%raft state. 1Aut#1 is %efinitel! an accepta4le alternati/e. 3,7egge% 1Aut# is also an option for certain
cases. Rea% more a4out t#e 1Aut# specification at #ttpJ//oaut#.net/%ocumentation/spec/.
1pen&D is an a%%itional option. owe/erC it is recommen%e% t#at 1pen&D 4e use% as an additional
aut#entication optionC le/eraging 1Aut# as primar!. Rea% more a4out t#e 1pen&D specification at
#ttpJ//openi%.net/%e/elopers/specs/.
Transport Sec#rity
All aut#entication s#oul% use $$7. 1Aut#2 reDuires t#e aut#oriAation ser/er an% access to9en
cre%entials to use T7$.
$witc#ing 4etween TTP an% TTP$ intro%uces securit! wea9nesses an% 4est practice is to use T7$
4! %efault for all communication.
.#thori/ation
Aut#oriAation for ser/ices is not reall! an! %ifferent t#an aut#oriAation for an! application. &tBs 4ase%
on t#e DuestionC FDoes t#is principal #a/e t#e reDueste% permission on t#e gi/en resource)G ?i/en
t#at simple trifecta of %ata 0principalC resourceC an% permission2C itBs fairl! eas! to construct an
aut#oriAation ser/ice t#at supports t#e concepts. "#ere Principal is t#e person or s!stem w#o is
grante% a permission on a resource. *sing t#ose generic conceptsC it is possi4le to #a/e a cac#ea4le
access control list 0A372 for eac# principal.
.pplication Sec#rity
T#e same principles in %e/eloping a secure we4 application #ol%s true for R($Tful ser/ices.
:ali%ate all input on t#e ser/er. Accept F9nownG goo% input an% reEect 4a% input.
Protect against $87 an% ;o$87 inEection.
1utput enco%e %ata using 9nown li4raries suc# as .icrosoft\s Anti,<$$ or 1"A$P\s
Anti$amm!.
Restrict t#e message siAe to t#e e@act lengt# of t#e fiel%.
$er/ices s#oul% onl! %ispla! generic error messages.
3onsi%er 4usiness logic attac9s. >or e@ample coul% an attac9er s9ip t#roug# a multi,step
or%ering process an% or%er a pro%uct wit#out #a/ing to enter cre%it car% information)
7og suspicious acti/it!.
R($Tful $ecurit! 3onsi%erationsJ
:ali%ate =$1; an% <.7 for malforme% %ata.
:er4s s#oul% 4e restricte% to t#e allowa4le met#o%. >or e@ampleC a ?(T reDuest s#oul% not 4e
a4le to %elete an entit!. A ?(T woul% rea% t#e entit! w#ile a D(7(T( woul% remo/e t#e entit!.
-e aware of race con%itions.
AP& gatewa!s can 4e use% to monitorC t#rottleC an% control access to t#e AP&. T#e following can 4e
%one 4! a gatewa! or 4! t#e R($Tful ser/ice.
.onitor usage of t#e AP& an% 9now w#at acti/it! is goo% an% w#at falls out of normal usage
patterns.
T#rottle AP& usage so t#at a malicious user cannot ta9e %own an AP& en%point 0D1$ attac92 an%
#a/e t#e a4ilit! to 4loc9 a malicious &P a%%ress.
$tore AP& 9e!s in a cr!ptograp#icall! secure 9e!store.
Cachin! and Scalability
3ac#ing en#ances scala4ilit! 4! ena4ling la!ers in t#e s!stem to eliminate remote calls to retrie/e
reDueste% %ata. $er/ices en#ance cac#e,a4ilit! 4! setting #ea%ers on responses. *nfortunatel!C
cac#ing,relate% #ea%ers in TTP 1.0 are %ifferent t#an t#ose in TTP 1.1C so ser/ices s#oul% support
4ot#. -elow is a ta4le of minimal #ea%ers reDuire% to support cac#ing for ?(T reDuestsC along wit# a
%escription of appropriate /alues.
HTTP Header Description E"ample
Date Date an% time t#e response was returne% 0in
R>31123 format2.
DateJ $unC 0' ;o/ 1994
05J49J3+ ?.T
3ac#e,3ontrol T#e ma@imum num4er of secon%s 0ma@ age2 a
response can 4e cac#e%. owe/erC if cac#ing is
not supporte% for t#e responseC t#en no,cac#e is
t#e /alue.
3ac#e,3ontrolJ 3'0
3ac#e,3ontrolJ no,cac#e
(@pires &f ma@ age is gi/enC contains t#e timestamp 0in
R>31123 format2 for w#en t#e response e@piresC
w#ic# is t#e /alue of Date 0e.g. now2 plus ma@
age. &f cac#ing is not supporte% for t#e responseC
t#is #ea%er is not present.
(@piresJ $unC 0' ;o/ 1994
05J49J3+ ?.T
Pragma "#en 3ac#e,3ontrol is Bno,cac#eB t#is #ea%er is
also set to Bno,cac#eB. 1t#erwiseC it is not present.
PragmaJ no,cac#e
7ast,.o%ifie% T#e timestamp t#at t#e resource itself was
mo%ifie% last 0in R>31123 format2.
7ast,.o%ifie%J $unC 0' ;o/
1994 05J49J3+ ?.T
To simplif!C #ereBs an e@ample #ea%er set in response to a simple ?(T reDuest on a resource t#at
ena4les cac#ing for one %a! 024 #ours2J
)acheG)ontrol/ 8:4EE
!ate/ Ced, 27 Deb 2E12 23/E1/1E &+T
LastG+odified/ +on, 28 Deb 2E11 13/1E/14 &+T
"xpires/ Thu, E1 +ar 2E12 23/E1/1E &+T
An% 4elow is an e@ample of a similar response t#at %isa4les cac#ing altoget#erJ
)acheG)ontrol/ noGcache
Pragma/ noGcache
The ETa! Header
T#e (Tag #ea%er is useful for /ali%ating t#e fres#ness of cac#e% representationsC as well as #elping
wit# con%itional rea% an% up%ate operations 0?(T an% P*TC respecti/el!2. &ts /alue is an ar4itrar!
string for t#e /ersion of a representation. owe/erC it also s#oul% 4e %ifferent for eac# format of a
representationHt#e (Tag for a =$1; response will 4e %ifferent for t#e same resource represente% in
<.7. T#e /alue for t#e (Tag #ea%er can 4e as simple as a #as# of t#e un%erl!ing %omain o4Eect 0e.g.
14Eect.#as#co%e02 in =a/a2 wit# t#e format inclu%e% in t#e #as#. &t is recommen%e% to return an (Tag
#ea%er for eac# ?(T 0rea%2 operation.
HTT) Status Codes $To 12&
-elow are t#e most commonl!,use% TTP status co%es returne% from R($Tful ser/ices or AP&s along
wit# a 4rief summar! of t#eir commonl!,accepte% usage. 1t#er TTP status co%es are use%
occasionall!C 4ut are eit#er specialiAations or more a%/ance%. .ost ser/ice suites are well ser/e% 4!
supporting onl! t#eseC or e/en a su4,set.
#$$ %&'( 6 ?eneral success status co%e. .ost common co%e to in%icate success.
#$) %*RE+TED( 6 $uccessful creation occurre% 0/ia eit#er P1$T or P*T2. $et t#e 7ocation #ea%er to
contain a lin9 to t#e newl!,create% resource. Response 4o%! content ma! or ma! not 4e present.
#$, %-& *&-TE-T( 6 $tatus w#en wrappe% responses are not use% an% not#ing is in t#e 4o%! 0e.g.
D(7(T(2.
.$, %-&T /&D010ED( 6 *se% in response to con%itional ?(T calls to re%uce 4an%,wi%t# usage. &f
use%C must set t#e DateC 3ontent,7ocationC (tag #ea%ers to w#at t#e! woul% #a/e 4een on a regular
?(T call. T#ere must 4e no response 4o%!.
,$$ %B+D RE23EST( 6 ?eneral error w#en fulfilling t#e reDuest woul% cause an in/ali% state.
Domain /ali%ation errorsC missing %ataC etc. are some e@amples.
,$) %3-+3TH&R04ED( 6 (rror co%e for a missing or in/ali% aut#entication to9en.
,$. %1&RB0DDE-( 6 (rror co%e for user not aut#oriAe% to perform t#e operationC %oesnBt #a/e rig#ts
to access t#e resourceC or t#e resource is una/aila4le for some reason 0e.g. time constraintsC etc.2.
,$, %-&T 1&3-D( 6 *se% w#en t#e reDueste% resource is not foun%C w#et#er it %oesnBt e@ist or if
t#ere was a 401 or 403 t#atC for securit! reasonsC t#e ser/ice wants to mas9.
,$5 %*&-160*T( 6 "#ene/er a resource conflict woul% 4e cause% 4! fulfilling t#e reDuest.
Duplicate entriesC %eleting root o4Eects w#en casca%e,%elete not supporte% are a couple of e@amples.
7$$ %0-TER-+6 SERVER ERR&R( 6 T#e general catc#,all error w#en t#e ser/er,si%e t#rows an
e@ception.
#dditional Resources
4oo0s
R"#T %PI !esign Ruleboo,C .ar9 .asseC 2011C 1\Reill! .e%iaC &nc.
R"#Tful Ceb #ervicesC 7eonar% Ric#ar%son an% $am Ru4!C 2005C 1\Reill! .e%iaC &nc.
R"#Tful Ceb #ervices )oo,boo,C $u44u AllamaraEuC 2010C 1\Reill! .e%iaC &nc.
R"#T in Practice/ Hypermedia and #ystems %rchitectureC =im "e44erC et al.C 2010C 1\Reill! .e%iaC
&nc.
%PIs/ % #trategy &uideC Daniel =aco4son] ?reg -rail] Dan "oo%sC 2011C 1BReill! .e%iaC &nc.
2ebsites
#ttpJ//www.restapitutorial.com
#ttpJ//www.ics.uci.e%u/Kfiel%ing/pu4s/%issertation/restLarc#Lst!le.#tm
#ttpJ//www.Eson.org/
#ttpsJ//git#u4.com/tfre%ric#/DateA%apter=
#ttpJ//openi%.net/%e/elopers/specs/
#ttpJ//oaut#.net/%ocumentation/spec/
#ttpJ//www.Eson.org/=$1;ReDuest.#tml
#ttpJ//la4s.omniti.com/la4s/Esen%
#ttpJ//ena4le,cors.org/
#ttpJ//www.o%ata.org/%ocumentation/uri,con/entionsS>ilter$!stem8uer!1ption
#ttpJ//ro!.g4i/.com/untangle%/2005/rest,apis,must,4e,#!perte@t,%ri/en
#ttpsJ//%e/eloper.lin9e%in.com/apis
#ttpJ//%e/elopers.face4oo9.com/%ocs/reference/api/
#ttpsJ//%e/.twitter.com/%ocs/api
#ttpJ//momentEs.com/
#ttpJ//www.%ateEs.com/

RESTful Best Practices-V1 1

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

RESTful Best Practices-V1 1

Uploaded by

Copyright:

Available Formats

RESTful Service Best Practices

RESTful Service Best Practices

You might also like