RESTful Service Best Practices Recommendations for Creating Web Services

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
05/29/12
Page 2 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 0 AT(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 0 AT(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 05/29/12 www.RestApiTutorial.com Page 3 of 34
RESTful Service Best Practices 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
05/29/12
Page 4 of 34
Document History
Date >e4 10C 2012 Apr 24C 2012 .a! 29C 2012 Version Draft /1.0 /1.1 Description &nitial %raft /ersion. &nitial pu4lic 0non,%raft2 /ersion. .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.
05/29/12
Page 5 of 34
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% www.RestApiTutorial.com Page ' of 34
05/29/12
RESTful Service Best Practices 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.
Mani ulation of Resources Throu!h Re resentations

"#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-descri ti"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!.
Hy ermedia 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
RESTful Service Best Practices .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! 05/29/12 www.RestApiTutorial.com Page 5 of 34
RESTful Service Best Practices 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( Ti s
"#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 05/29/12 www.RestApiTutorial.com Page 9 of 34
RESTful Service Best Practices 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. in t#e HTTP erbs, !"L"T" section 4elow. owe/erC rea% t#e ca/eat on D(7(T(
?(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. 05/29/12 www.RestApiTutorial.com Page 10 of 34
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. must return t#e same response e/er! time. owe/erC safet! %oes not mean t#at t#e ser/er
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.
05/29/12
Page 11 of 34
RESTful Service Best Practices 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 05/29/12 www.RestApiTutorial.com Page 12 of 34
RESTful Service Best Practices 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 ?(T P*T /customers 200 01P2C list of customers. *se paginationC sorting an% filtering to na/igate 4ig lists. 404 0;ot >oun%2C unless !ou want to up%ate/replace e/er! resource in t#e entire collection. www.RestApiTutorial.com /customers/{id} 200 01P2C single customer. 404 0;ot >oun%2C if &D not foun% or in/ali%. 200 01P2 or 204 0;o 3ontent2. 404 0;ot >oun%2C if &D not foun% or in/ali%. Page 13 of 34
05/29/12
RESTful Service Best Practices P1$T D(7(T( 201 03reate%2C B7ocationB #ea%er wit# lin9 to /customers/Qi%R containing new &D. 404 0;ot >oun%2C unless !ou want to %elete t#e w#ole collectionHnot often %esira4le. 404 0;ot >oun%2. 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
05/29/12
Page 14 of 34
"eso#rce U"I +-amples

To insert 0create2 a new customer in t#e s!stemC we mig#t useJ P'#T http/00www.example.com0customers To rea% a customer wit# 3ustomer &DS 33245J &"T http/00www.example.com0customers033245 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 05/29/12 www.RestApiTutorial.com Page 15 of 34
RESTful Service Best Practices 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... %e4ate) &t does e@ist. (ssentiall!C it 4oils %own to t#is Duestion... a/enBt #ear% of t#at
$#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
RESTful Service Best Practices &"T http/00www.example.com0customers033245 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 P'#T http/00www.example.com0customers 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! Re resentations
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
RESTful Service Best Practices *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 &"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 0 AT(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$ 05/29/12 www.RestApiTutorial.com Page 15 of 34
RESTful Service Best Practices 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 .(T 1D 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. 05/29/12 www.RestApiTutorial.com ereBs w#at t#e response woul% Page 19 of 34
RESTful Service Best Practices 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.
05/29/12
Page 20 of 34
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 05/29/12 www.RestApiTutorial.com Page 21 of 34
RESTful Service Best Practices 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.
Su
ortin! 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/.
Su
ortin! .S%+)
=$1;P gets aroun% t#e 4rowser limitation 4! utiliAing ?(T reDuests to perform all ser/ice calls. &n 05/29/12 www.RestApiTutorial.com Page 22 of 34
RESTful Service Best Practices 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 05/29/12 www.RestApiTutorial.com Page 23 of 34
RESTful Service Best Practices 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.
05/29/12
Page 24 of 34
,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 Res onses

>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. 05/29/12 www.RestApiTutorial.com Page 25 of 34
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
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
RESTful Service Best Practices $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 05/29/12 www.RestApiTutorial.com Page 25 of 34
RESTful Service Best Practices 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. !!!!,..,%%BTB JmmJss.$$$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% ttp ea%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 05/29/12 www.RestApiTutorial.com Page 29 of 34
RESTful Service Best Practices 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.
05/29/12
Page 30 of 34
.#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!. :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.
R($Tful $ecurit! 3onsi%erationsJ
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 05/29/12 www.RestApiTutorial.com E"ample Page 31 of 34
RESTful Service Best Practices Date 3ac#e,3ontrol Date an% time t#e response was returne% 0in R>31123 format2. 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. &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. DateJ $unC 0' ;o/ 1994 05J49J3+ ?.T 3ac#e,3ontrolJ 3'0 3ac#e,3ontrolJ no,cac#e
(@pires
(@piresJ $unC 0' ;o/ 1994 05J49J3+ ?.T
Pragma 7ast,.o%ifie%
"#en 3ac#e,3ontrol is Bno,cac#eB t#is #ea%er is PragmaJ no,cac#e also set to Bno,cac#eB. 1t#erwiseC it is not present. 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.
05/29/12
Page 32 of 34
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.
05/29/12
Page 33 of 34
#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 %rchitecture C =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/
05/29/12
Page 34 of 34

RESTful Service Best Practices Recommendations for Creating Web Services

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

RESTful Service Best Practices Recommendations for Creating Web Services

Diunggah oleh

Hak Cipta:

Format Tersedia

RESTful Service Best Practices