5/23/2014 REST-ful URI design | 2PartsMagic Blog

http://blog.2partsmagic.com/restful-uri-design/ 1/17
RESTfulURIdesign
ThispostisaboutURInaming.DesigningURInames.Sometipsandrulesandconventionsthatyoucanfollowwhenfiguring
outyourapplicationsURIs.ThefocusisonURIsforRESTfulapplications.Butmanyofthetipsapplytoanykindof
websiteorapplication.
RESTfulURIsandnonRESTfulURIs
ARESTfulURIisaURIthatidentifiesadomainresource(likeabookorashelforabookloaninalibraryapplication)rather
thananapplicationresource(likeawebpageoraforminyourapplicationorwebsite).
TypicallyRESTfulURIsareforAPIs.Forprogrammers.Butinmanycasestheywillservejustaswellforaregular
website.
nonRESTfulURIsaremorelikelytoidentifyapplicationresourceslikewebpagesratherthandomainresources:
/admin/updatebook.jsp?book=5
/bookview.jsp?book=5
/bookandreviews.jsp?book=5
PS:TherecanbeconfusionaboutURIsandURLs(andURNs!).TogetaURLjusttackonaserver(example.com)anda
protocol(httporftp)toaURI(/example):http://example.com/example.TheURIidentifiestheresource.AndaURLaddssome
informationabouthowtogetit.
URIsdonotmatterwithRESTfulapplications
Thisiswhatsomepeoplesay.Seethecommentsbelow.Butisnottrue:URIsdomatter.URIdesignmatters.AndURI
designforRESTfulapplicationsmattersevenmore.
ThereasonisthatRESTfulappsareallaboutdomainresources(likebooksandshelvesandloansinalibraryapplication)rather
thanapplicationresources(likeformstoreserveabookorpagesdisplayingabookorwhohasloanedwhat).
WithRESTfulapplicationsthefirstthingyouneedtodoistoidentifytheresourcesyouarerepresentinginyoursystem.And
URIdesignisallabouthowyoucanconsistentlynameeveryoneofthoseresources.
WhatarethecriteriaforagoodRESTfulURI?
IassertagoodRESTfulURIis:
Short(aspossible).Thismakesthemeasytowritedownorspellorremember.
Hackableupthetree.Theusershouldbeabletoremovetheleafpathandgetanexpectedpageback.e.g.
2PartsMagicBlog
Bloggingwebsoftwaredevelopment
2PartsMagic RESTfulURIdesign About2PartsMagic
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 2/17
http://example.com/cars/alfaromeos/gtyoucouldremovethegtbitandexpecttogetbackallthealfaromeos.
Meaningful.Describestheresource.IshouldhaveahintatthetypeofresourceIamlookingat(ablogpost,ora
conversation).IdeallyIwouldhaveaclueabouttheactualcontentoftheURI(e.g.aurilikeuridesignessay)
Predictable.Humanguessable.IfyourURLsaremeaningfultheymayalsobepredictable.Ifyourusersunderstandthem
andcanpredictwhataurlforagivenresourceisthenmaybeabletogostraighttherewithouthavingtofindahyperlink
onapage.IfyourURIsarepredictable,thenyourdeveloperswillarguelessoverwhatshouldbeusedfornewresource
types.
Helpvisualizethesitestructure.Thishelpsmakethemmorepredictable.
Readable.
Nouns,notverbs.
Queryargs(everythingafterthe?)areusedonquerying/searchingresources(exclusively).Theycontaindatatheaffectsthe
query.
Consistent.Ifyouuseextensions,donotuse.htmlinonelocationand.htminanother.ConsistentpatternsmakeURIsmore
predictable.
Stateless.
Returnarepresentation(e.g.XMLorjson)basedontherequestheaders,likeAcceptandAcceptLanguageratherthana
changeintheURI.
Tiedtoaresource.Permanent.TheURIwillcontinuetoworkwhiletheresourceexists,anddespitetheresourcepotentially
changingovertime.
ReportcanonicalURIs.IfyouhavetwodifferentURIsforthesameresource,ensureyouputthecanonicalURLinthe
response.
Followsthediggingdeeperpathandbackspaceconvention.URIpathcanbeusedlikeabackspace.
Usesname1=value1name2=value2(akamatrixparameters)whenfilteringcollectionsofresources.
Someofthesecriteriapullagainsteachother.Forexample,howcanImakeameaningfulyetshorturi?URIdesignrightly
remainsanartnotascience.
TipsforcreatinggoodRESTfulURIs
Lowercase.Mixedcasecanbehardertotypein.Upperand,arguably,mixedcasecanbelessreadable.Mixedcasemay
alsocauseambiguity.Ishttp://example.com/TheBigFatCatdifferenttohttp://example.com/thebigfatcat
Usehypensratherthanspacesorunderlines.hyphensseemtobethewaymostsitesdoit.Theresultingurlisreadable
enough.using_underlines_in_your_urlmaynotbeasSEOfriendly.AndIfindtheyarenotasastheticashypens.Spacesin
urlsquicklydegradeintoasewerofurlencoded%20s.
Useapluralpathforcollections.e.g./conversations.
Putindividualresourcesunderthepluralcollectionpath.e.g./conversations/conversation9.Othersmaydisagreeandargue
itbesomethinglike/conversation9.ButIasserttheindividualresourcefitsnicelyunderthecollection.PlusitmeansIcan
hacktheurlupalevelandremovetheconversationpartandbeleftonthe/conversationspagelistingall(orsome)ofthe
conversations.
Favorhackableurlsoverdirecturls.
Thingstoavoid
Avoidqueryargsonannonquery/nonsearchresource.e.g.prefer/conversations/conversation12over
/conversations/conversation.php?conversation_id=12
DonotusemixedoruppercaseinURIs.
Avoidextensions(avoid.enor.fravoid.htmlor.htmor.phpor.jspavoid.xmlor.json).
DonotusecharactersthatrequireurlencodinginURIs(e.g.spaces).
AvoiddirectURIse.g./todoitem{id}forhierarchicaldata.Insteadexposeitscontext:/conversations/conversation9help
me/todolist8setuptasks/todoitem12installapache
BenefitsofgoodURIdesign
OtherwebsitesmayuseyourURIsmoreiftheylookgood.
OtherwebsitesmayuseyourURIsmoreiftheydonotchange.Ifthereisnolinkrot.
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 3/17
GoodURIsimproveyoursiteusability.
ReadableURIsincreaseyoursearchenginetraffic.PeopleactuallyseeandreadURLsinGooglessearchresults.Andthey
aremorelikelytogotoapageifthenameofthepagematcheswhattheyarelookingfor.
HowgoodURIdesignimprovesusability
UserscanfindtheirwayaroundmoreeasilywhentherearegoodURIs.Theyhaveachanceofgettingthemselvesunstuck
insidethesitestructure.e.g.iftheyareat/conversations/conversation10/todolist12theycaneasilyenoughpopupto
/conversationswhereallthecurrentconversationsaredisplayed.
AgoodprogrammerlookingatwelldesignedURIsinaRESTfulAPIshouldbeabletovisualizeyourAPImerelybyknowing
someoftheURLs.
NonRESTfulURLs
Ihavealwaysaimedtocreatedecenturls.InnonRESTfulappstheywouldbegoodsolidurlslike:
http://rimuhosting.com/ticket/startticket.jsp
https://pingability.com/cp/register.jsp
http://rimuhosting.com/order/startorder1.jsp?type=2&tvps
TypicallywhenthereisadifferentkindofpageIcreateanJSPforthatpage.Andthepagenamewillreflectwhateveris
happeningonthatpage.
NonRESTfulURIsarefine,theyarejustnonRESTful.
ThispostisnotadebateaboutwhichisbetteroutofRESTfulandnonRESTfulURIs.Thispostisaboutwhatmakesagood
RESTfulURI.IfyourURIisnonRESTfulitissimplynonRESTful,andImakenoclaimthatitisgoodorbad.
RESTfulURIs
TheRedRatateamhasrecentlystartedtryingtocreateanapplicationandwewouldlikeittobeaRESTfulapplication.
RESTfulapplicationsdonotimplementaspecification(likeSOAP,orXMLRPC,orATOM).Thereisnovalidationservicethat
willtellmeifmyRESTfulapplicationisREST1.0compliant.ThereisnoREST1.0BTW.
InsteadRESTfulapplicationsareapplicationsthatfollowRESTfulconventions.
AndthereareconventionsaroundwhatmakesaRESTfulURI.
IvefoundthatcomingupwithRESTfulURIsthatI,andothers,thinkfollowsproperRESTfulconventionsisdifficult.
ButthedifficultycomesbecauseoftheimportanceofgoodURIdesign.Notsomuchthatitfollowssomeconventionthata
bunchoftechnologistshavecomeupwith.Butbecauseitimprovesenduserusability.
Examplesof(possibly)RESTfulURIs
InaquicklyrecognizableasRESTfulappwewouldpossiblyhaveURLslike.e.g.
http://rimuhosting.com/users/user9/contactdetails
http://rimuhosting.com/planstype=vpstoshowVPSplans
http://rimuhosting.com/plans/planmiro2btoshowtheMIRO2Bplan.Aside:thisredrata.comWordPressblogrunsona
RimuHostingMiro2plan.
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 4/17
http://rimuhosting.com/carts/cart2/server1aserverplanaddedtothecart,inpreparationofcheckout
5developersaninfiniteselectionofURLschaosensues
IcameupwiththosesampleURLsjustnow.IfIweretocomeupwiththesameresourcestomorrowwouldthatlistlookthe
same?Whatifanotherdeveloperinmyteamattemptedthesametask?
Wouldthenamesbesimilar?Wouldweargueendlesslyaboutwhichwasthebetterway?Wouldtherebeanyconcreteguidelines
onwhichwecouldselectonesetoveranother?WouldweevenbeawareoftheURIdesignimportancetoworry?Wouldusability
issuesanddevelopmentchaosensue?
Howtodecideonwhichtemplateorconventionsdoyouuse?Howdoyougeteveryoneonthesamepage?Howcanyoumakeit
sotwodevelopersindependentlyaddinganewresourcetotheappwouldusethesameorsimilarURI?
InordertotryandgetsomeconsistencyoverhowwedesignurlsinRedRataRESTfulappswehavetriedtocomeupwitha
conventionforustouse.Thatconventionandadiscussionofthealternativesfollows.
Nouns,notverbs
RESTishURLsidentifyresources.Nouns.Theytellyouwhattheyare.
RESTfulURIsshouldnottellyouwhattheydo.NogetPlan.Norstartorder.
ThedocomeswhenyouapplyaverbanHTTPmethodtotheURL.e.g.aHTTPPUTtoaURImeansupdatethatresource.A
DELETEmeanstodeleteit.APOSTtypicallymeanscreatesomethingforme(e.g.aneworder,orashoppingcart).
StatelessURIs
Anexample.OnRimuHostingwehavesomelongrunningoperations.e.g.whenwemoveaVPSfromonehostserveracrossthe
globetoadifferentdatacenter.SowecreateamovestatusURLandgiveitastatusid.AndthenweuseAjaxtokeeppushing
updatestothatURL.Ortheusercanreloadthepage.
Thereisaproblem.ThatURLonlyworksforthatuseronthatsession.Theycouldnotbookmarkit,gohome,andseeitathome.
TheycannotsendittoacolleagueandsayKeepaneyeonthismoveforme.
GoodURIs(RESTfulorotherwise)shouldbestateless.IfIamlookingatadocumentIshouldbeabletosharethatURLwith
someoneandtheyshouldbeabletoaccessthesameresource.
WhattheyseemaydifferfromwhatIsee.e.g.sinceImaybeloggedinasanadminonasiteandseeafewmoreoptionsthan
theydoasaguest.Butthisisjustadifferentrepresentationofthesameresource.Ortheymayevengetanotauthorized
responseiftheyareaguest,oraloggedinuserwithouttheauthoritytoseetheresource.
TogetastatelessURIavoidrelianceonsessionattributes.Transientthings.Ifyouneedtostoresomething,storeitinadatabase
(wheredatabaseisprobablysomeSQLdatabase,butanythingthatisaccessiblebysomeonewithadifferentsessionIDwilldo).
Examples:
Hey,haveIgotallthethingsyouneededinmyshoppingcart?AURLofhttp://example.com/shoppingcartwouldnotbe
somethingthattheotherpersoncouldeasilysee.IftheURIwashttp://example.com/shoppingcarts/cart12thenitcould
potentiallybevisible(e.g.ifyouhadsetapublicflagonthecart,orifyouandacolleaguehadalogineachtoapurchasing
accountonexample.com).
Example:
Hey,whataddressdoIneedtosetonmyaccount?Iftheurlishttp://example.com/addressthenitlikelyrepresentstheaddress
ofthecurrentlyloggedinperson.AndwhatIwillsee(myaddress)isadifferentresourcefromwhatyouwillsee(youraddress).
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 5/17
Sametypeofresource(address).Differentinstance:minevs.yours.
InthiscaseconsideraURIdesignofhttp://example.com/users/user9/address.
Thenitisclearthatwearetalkingabouttheaddressofaspecificperson.Whetheryoucanseemyaddressisadifferentmatter.
StatelessURLscanimprovescalability
AbeneficialsideeffectofstatelessURIs,whereyouavoidstoringattributesassociatedwithasessionisthatyourapplicationcan
scaleacrosshardwaremoreeasily.Asitwillnotmatter,ormatterasmuchiftheyshiftfromonewebservertoanothersincethe
URLstheyseedonodependonsomesessionstate.e.g.worstcasescenariotheymayjustneedtorelogin.Toreestablishtheir
identity.
PersonalURLs
ThereisvaluehavingaURIlikehttp://example.com/contactdetails(meaningmycontactdetails).Orpreferablysomethingthat
indicatesitbelongstothecurrentuser,like,http://example.com/users/userme/contactdetails.
e.g.youmayhaveastaticpagethatwantstolinktotheuserscontactdetails.Andatthetimeyoushowthepagetheymaynotbe
loggedin.
Inthatcasehttp://example.com/users/userme/contactdetailscouldpromptforalogin.Oriftheuserisloggedintheythepage
couldredirecttoURLlike,say,http://example.com/users/user9peter/contactdetails
Theredirectinthiscaseisimportant.Sincethepageonwhichtheuserendsupistheircontactdetailsresource.Whereas
http://example.com/users/userme/contactdetailsisaresourcetofindyourcontactdetailslocation.
Summary:ifaresourceiscontextsensitive(e.g.toacurrentuser)createaseparateresourcefinderURL.Makeitclearthat
resourceURIiscontextsensitive(e.g.includingwordslikemeormyinit).Andhavethatresourceredirecttotheactualresource
whenitisused.
Furtherexample:http://example.com/forecasts/cambridge/todayredirectsto,say,http://example.com/forecasts/cambridge/2009
0426
Extensionornoextension
IfyouuseJSPthenyourfilesprobablyhavea.jspextension.AndsimilarlyforPHPandotherapps.Inanidealworldthe
technologyyouuseonthebackendshouldnotforceitswayintotheusersface.
Somesiteshavea.enURIforanEnglishversionofthecontentandadifferentURIwitha.frextensionforaFrenchlocalized
versionofthepage.Woulditnotbebetterifausercouldgotohttp://example.com/aboutusandgetthepageintheirpreferred
language.AndthensharethatURLwithsomeoneelsewhoseesitintheirownlanguage?
Someapplicationsreturndifferentdataiftheuseraddsadifferentextension.e.g.theymayaskforcontacts.xmlorcontacts.json.
ButdifferentURIsimplydifferentresources.Arethetwodataformatsreallytwodifferentresources?Orjusttwodifferent
representationsofthesameresource.
WithHTTPthereareotherwaysyoucannegotiatecontent.e.g.viatheAcceptheader.
IassertthatRESTfulURIsshouldidentifyasingleresource.Anddifferentrepresentationsofthatresourcecanbenegotiated.
e.g.viaHTTPheaders.Iassertthatthingslikelanguagelocalizations,dataformats,readonlyviews,HTMLforms,summary
views,detailviews,etc,arealljustdifferentrepresentationsofthesameresource.Iassertdevelopersshouldworktokeepall
thoserepresentationsonthesameURI.
Iassertthatweavoidextensionstoindicatetherepresentationoftheresource.
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 6/17
UsingAcceptHTTPrequestheaderstonegotiateviews.
HavingallrepresentationsofaresourceonasingleURIcanbeatrickytaskfordeveloperstopulloff.Itrequireshavingalotof
controloverreceipt/dispatchofHTTPrequests.AndfullandeasycontrolofHTTPrequestandresponseheaders.Nottomention
beingabletoserveupdifferenthumanandmachinelanguagesandviewsforresources.
Standardwaystonegotiatetherepresentationofaresource:
Accept:text/htmlwillreturnafullwebpagewithsitenavigationandotherlinks
AcceptLanguagetocontrolthelocalizationoftheresourcebetweendifferenthumanlanguages.
Accept:application/xmlandapplication/jsontogetbackdatainthesepopularformats.
StandardAcceptheadersbreakdownwithsomeviewtypes
Buthowdoyounegotiateotherrepresentationslikeasummaryreadonlyviewofaresource/customer9summary?Oradetail
view/customer9?detail=Y.Oraformtoeditthatperson:/customer9/edit
TheseareintroducingnewURIs(suggestingthesearethereforedifferentresources).YetIamassertingthatthesethingsare
mererepresentationsofthesameresource,notdifferentresources.
Buthowelsetosolvetheproblem?TheseareallHTMLpages(forargumentsake).Andweveonlygottheonetext/htmlmedia
type.
Orhavewe?
UsingvendorspecificAcceptheaders
Instead,RedRatawillbetrialingamethodtoleavetheURIsaloneandjustuseadifferentAcceptheaderfortheodd/particular
representationsweneed.Wewillbeusingvndvendorspecific,madeupmediatypes.
TheRedRatavendorspecificAccepttypes
RedRatausesthe{type}/vnd.{company}{type}+{subtype}convention.
e.g.text/vnd.redrata.summary+htmlapplication/vnd.redrata.deep+json.
Wewillbeusingthosetypestodifferentiatebetween,sayaregularAccept:text/html(returningapagewiththeresourceandall
thesitenavigation)andsaythefollowing:
Accept:text/vnd.redrata.summary+htmlreturns,say,aHTMLdivelementcontainingareadonlysummaryofaresource.
e.g.forapersonmaybejusttheirname.Ornameandemail.Butnotalltheirdetails:likeaddress,phone,notes.
Accept:text/vnd.redrata.detail+htmlthefulldetailfor,say,aperson.Butitwouldexcludetheflufflikesitenavigation,
ads,andotherthingsnotdirectlyrelatedtothepersonresource.
Accept:text/vnd.redrata.edit+htmlreturns,say,aHTMLdivelementcontainingaformelementforeditingtheresource.
Withtheformprepopulatedwiththeresourcescurrentsettings.
Accept:application/vnd.redrata.deep+jsonforadeepcopyofaresourcesJSONandallitssubresources.i.e.grabbing
everythinginoneHTTPrequest
Accept:application/vnd.redrata.shallow+jsonforashallowcopyofaresourcesJSON(excludinganysubresources).i.e.
grabbingeverythinginoneHTTPrequest
Accept:application/vnd.redrata.shallow+xmlandapplication/vnd.redrata.deep+xmlworkthesameway,butforXML
IamnotawareofanyoneelseusingthisAcceptapproachwithvnd(vendorspecific)mediatypes.
Ifyouthinktheapproachmakessense,pleaseuseitinyourappsandhelpmakeournonconventionalapproachmore
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 7/17
conventional.Heck,wemayevengosofarastoregisterthosemediatypes.
Moreavailableviewsofaresource=>moreusableAPI
OneofthegoalsRedRatahasisthattheapplicationswecreatewithourRESTfulAPIswillbeeasilyembeddedintoour
customerssites.e.g.withaquickJavascript/ajaxcalltoyankabitofinformationoutofourapp.
Byofferingavarietyofviews(inHTMLandJSON/XML)wehaveabetterchanceofbeingabletoreturnsomethingmost
suitableforourcustomersandusers.
DocoolURIseverchange?
W3.orgassertsthatcoolURIsdonotchange.
Iassertthatseemsagoodguidelineinmostcases.
Balancethatagainst:
Keepingthingsbackwardscompatibleaddsextraeffort.
Applicationresourcestructureschange.AndthatshouldnaturallycauseURIstochangesotheybetterreflectreality.
WecanimproveourURIsovertime.
GoodRESTfulapplicationsshouldrepresenttheirstateintheirrepresentations.Forexamplebyprovidinghyperlinksto
otherresources.AgoodRESTfulapplicationshouldbefullynavigabletoanyoneiftheystartatthe/URI.
Ifgooglecanfollowlinksonyoursitetogettothecontent,thentheuserwilllikelybeabletofinditagain.99%ofthe
pagesIneedtogetbacktoIgetbacktobysearchingforcontentonthatpage/resource.ParticularlywhenIrememberthe
domainitwasonandIcanslapasite:example.comintomygooglequery.
URIsdobreak.Itisjustafactoflife.People,andwebservicescope.Nooneornoserviceshouldexpecttorelyon
unchangingURLsandgetawaywithitfortolong.
ToavoidURIsthatchangeasmuchaspossibleconsiderkeepingchangeable/variableinformationoutoftheURI.e.g.Avoid
usingausersusernameintheirhomepageURLifthatusernamecanchange.Ratherusesomethingthatwillnotchange.e.g.a
databaseid.
MorereadableURIsusinguniqueidplusredundantinformation(UPRI)
HowdoyoubalanceURIsthatdontchange(implementedusingunique,immutabledatabaseids)withnicereadableURIs(where
thereadablebitforexampleausernameoraconversationorblogpostsubjectisliabletochange?
Considerusingthedatabaseidplussomeotherredundantinfo(likeausernameorname).Theredundantinformationisnot
necessarytofindtheresource.Ifyouhavetheunique,immutableid,likethedatabaseid,thenyoudonotcareabouttheotherbits
intheURI.
e.g./conversations/conversation9howdoichangebillingdetails
Canonicalurls:copingwithdifferentURIsforthesameresource
Withtheuniqueidplusredundantinformation(UPRI)approachyoucouldendupwithdifferentURIsforthesamething.And
thatisnotideal.
InthecaseofdifferentURIspointingtothesameresource(e.g.whenyouareusingunique,immutableidsplusredundantbits)
youshouldconsiderindicatinginyourresponsethecanonicalorpreferredlinkforthatresource.
YoucandothisinsideHTMLsHEADsRELtag.OrinHTTPresponseheaders.UsingLocation,ContentLocationorLink
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 8/17
e.g.seeGooglespostonspecifyingcanonicalURLsorMarkNottinghamsLinkheaderproposal.SeealsoBenRamseyscool
URIsdontchangepost.
Redirects/Locationswork,butwhowantstheHTTPlatencyoverhead?PlusifyouuseaprettyURIthatthengoesstraighttoa
differentlocation(andchangesthebrowseraddressbar)thennoonewillgettoappreciateyourpretty,readableURI.Andthey
willlikelyfeellessinclinedtoloveitandbookmarkitandtelltheirfriendsonsocialnetworkwebsitesaboutit.
Browserurlsareuserinterface(UI)
URLsthatappearinthebrowseraddressbararepartoftheUI(userinteraction).TheyMUSTbehackable.
SoanypathusedinabrowseryoudexpecttoproduceadecentHTMLpageallthewayupthetree.e.g.youdwanttheretobe
no404s.Noranyaccessdenieds.
Thediggingdeeperpathandbackspaceconvention
Generalrule:ifyouareonapageandyouareclickingintoanitemonthatpage,drillingdownintomoredetailonthatitem,
thenthewewouldgenerallyjustaddtheextrapathsegmenttotheoriginalURI.e.g.fromconversationpagetotodolistitem
wouldbe/conversations/conversation1becomes/conversations/conversation1/todolist5.Thusyoucangobacktowhereyou
werebyremovingtheendpathsegment.
Generalrule(rephrased):Ifyouareclickingdownaresourceheirarchy(e.gfromconversationstoconversationtoconversation
itemto)thebackkeySHOULDbethesameinmostcasesasremovingtheURLslastpathsegment.
Similarlyifyouareon/conversations/conversation1andyouclickonthealltodolistsinthisconversationlinkyoucouldend
upon/conversations/conversation1/todolists.Fromthereyouclickonaparticulartodolist.Inthiscaseyougetto
/conversations/conversation1/todolists/todolist5.Youcanremovethelastandendbackuponthepageyouhadcomefrom,
satisfyingthediggingdeeperpathandbackspacerule.Butnotethat/conversations/conversation1/todolists/todolist5and
/conversations/conversation1/todolist5willpointtothesameresource.SoyouwouldwanttousetheHTMLorresponse
headerstoindicatethecanonicalurl.
PuttingourURIdesignthoughtsintopractice
ThefirststepinURIdesignistoidentifyyourresources.Intheexamplesherewewillbetalkingaboutahypotheticalapplication
thatmanagesconversations.OK,itsnothypothetical.Itisanactualapplicationwearebuilding.Andthisistheactual
documentwherewetrytofigureoutwhatourURIsaregoingtolooklike.
Themainresources/thingsinourapplicationareconversations.Eachconversationcanhaveoneormoreconversationitemslikea
messagegoingbackorforthoratodolistorastatusupdate.Andsomeoftheconversationitemscanhavecollectionsofother
resources.e.g.atodolistcanhaveanumberofassociatedtodoitems.
ChoosingaURIschemesforresourcehierarchies
LetuslookatwhatURIswecouldusetorepresentourconversationrelatedresources.
pluralrootplussingularroot:e.g./conversationsand/conversation/{id}
/conversations:allconversations
/conversation/{id}:aspecificconversation(notesingularnotplural)
Cons:Youcanthacktheurl.Ifyouremovetheidyouget/conversationandnotthelistofconversationsyouwere
expecting/hopingfor(whichisat/conversations)
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 9/17
pluralsingularid:e.g./conversations/conversation/{id}
/conversations:allconversations
/conversations/conversation/{id}:aspecificconversation
Issue:whatisthepageat/conversations/conversationgoingtoshow?Doyouwantapagethere?Ifyoudonothaveapagethat
madesensetoshowtherethenthatURIisnotreallyhackable.
Issue:itiskindalong
pluralid:e.g./conversations/{id}
/conversations:allconversations
/conversations/{id}:aspecificconversation
Pro:vs.optionpluralrootplussingularrootyoucanremovebitsfromthepathandworkuptheownershipheirarchy
Cons:Ifyouwantedtouseaurllike/conversations/newthenyoudneedtobeabletodissambiguateaconversationlike
/conversations/5431.e.g.ifallyourconversationidsarenumbersthenthiscouldworkwell.Elseyoudneedtoavoidnaming
collisionsincaseyoueverhadaconversationidofnew.Ifthiscouldbethecaseyoumaybebetteroffusingthepluralname
andidtemplate.
Optionpluralididid/conversations/{id}/{id}/{id}
Whataboutwhenyouhavedeeplynestedresources?
/conversations:allconversations
/conversations/{id}:aspecificconversation
/conversations/{id}/{id}:aspecificconversationitem
/conversations/{id}/{id}/{id}:e.g.atodoitemonatodolistonaparticularconversation
Disadvantage:withdeeplynestedhierarchiesyoulosemeaningaboutwhateachpathis
pluralnameidnameidnameid:e.g./conversations/conversation/{id}/todolists/{id}/todos/{id}
/conversations/conversation/{id}/todolists/{id}/todos/{id}:e.g.atodoitemonatodolistonaparticularconversation
Advantage:youknowwhateachidmeans.
Disadvantage:Ifyouexpose/conversations/conversation/{id}/todolists/{id}/todos/{id}inabrowserurlbar,thenyoudneedto
supporthavingaUIforhavingeachpartofthatdirectorytree.e.g./conversations/conversation/{id}/todolists/{id}/todosyou
maywanttodothat,ifsofine.ElseifyoudontwanttoprovideaUIforthattherewouldbeanissue.e.g.usergetserrorpage.
MeaningtheURIisnotsohackable.
Optionpluralnameandid/conversations/conversation{id}
/conversations:allconversations
/conversations/conversation{id}:aspecificconversation
Pros:similartopluralid.
pluralnameandidnameandidnameandid:e.g./conversations/conversation{id}/todolist{id}/todo
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 10/17
{id}
Weextendthepluralnameandidfornestedanddeeplynestedresources.
/conversations:allconversations
/conversations/conversation{id}:aspecificconversation
/conversations/conversation{id}/todolist{id}/todo{id}:e.g.atodoitemonatodolistonaparticularconversation
Advantages:hackingtheurlbyremovingapathwillgiveyouthetodolist,thewholeconversation,orasetofconversations
AtRedRataweareoptingtousethispluralnameandidtemplatefornestedresources.
/conversations/conversation{id}/todolist{id}/todo{id}:e.g.atodoitemonatodolistonaparticularconversation.Andifyou
removethelastpathyouget/conversations/conversation{id}/todolist{id},thetodolistandallitsitems.Andifyouremovethe
lastpathfromthatyouget/conversations/conversation{id}theconversation.
Inthisexample,thereisnouserinterfacetotheURLtogetanindividualconversationitem.Whynot?Wellwhatifwedont
wanttoprovidethatpage?Theresourceexists.Wejustdontwantausertogothereandgetahey,nocontentwewanttoshow
youforthispagemessage
Ofcoursewemaychangeourmindslateronandwanttohaveapageavailablethatshowsjustasingleconversationitem.i.e.a
singlemessageinaconversation.Inthatcasewecanexposeaurllike(justaslashhasbeenadded):
/conversations/conversation{id}/todolist{id}/todo{id}
nameplusidplusredundant:e.g./conversations/conversation9whereisapacheinstalled
Wecanconverttheunique,butopaque,/conversation/conversation{id}tothejustaspermanentbutmorereadable
/conversation/conversation{id}{subject}
Wedothedatabaselookupbasedontheid.Weignorethesubject(asthatcouldchangeovertime).
Onourresponseweindicatethecanonicalresourcee.g./conversation/conversation{id}.
Pros:userfriendly,permanentURI
Cons:abitlong,abitofextraworktorespondwiththecanonicalresourcelocation.
SampleURLsfortheRedRatacommapp
Hackableurls:
/conversations/conversation{id}/todolist{id}/todo{id}
/conversations/conversation{id}/message{id}
/conversations/conversation{id}/email{id}
/conversations/conversation{id}/messages
/conversations/conversation{id}/messages/message{id}
/conversations/conversation{id}/messagenewforcreatingnewmessages.Afterthemessageiscreateditwillhaveanid.And
theurlwillbethesameexceptthenewbecomestheid.Niceandneat.
Creatingresources
Creatingnewresourcess(whenthatresourcesparentdoesnotexistyet)presentsaparticularchallengewithRESTful
applications.
TheRESTfulpolicingsquadswillknockonyourdoorifyouovertlyofferverbsinyoururls.Like/conversations/createnew
conversation.Thatisseenasexposingaprocessnotaresource.Youcouldalwayshaveyourdefenselawyerarguetheprocessis
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 11/17
theresource,Isuppose.
YoucouldsendaHTTPPOSTtoaURIlike/conversationstocreatearesourcewith.Butthatcouldbeambiguous.Whatwould
thatcreate?Aconversation?Whatifotherthingslivedunderconversations?Likestaff?Orauditlogs?Orbillablehours?
HerearesomeexamplesofURIswecoulduseinstead:
/conversations/conversatation{id}/messagenewexistingconversationcreatemessage
/conversations/messagenewcreateanewmessageandwhileweareatititwouldalsocreateanewconversationinwhichto
putit.
TheseURIswouldreturninformation(e.g.anHTMLform,oraprototypeJSON/XMLrepresentationonaHTTPGET).And
wouldcreatethenewresourceonaHTTPPOST.
HerearesomeURIswewouldlikelynotuse:
/conversations/conversatationnew/messagenewimplies/conversations/conversatationnewcreatesanewconverstation.But
thatisntsomethingwewanttoallowthemtodo.i.e.thisURIishackableinawaywedonotwantittobe
/conversations/conversatation/messagenewimpliesthesameas/conversations/messagenewbutifwehadnothingtoshowat
/conversations/conversatationthenthisurlwouldbehackableinabadway.
DirectURLsvs.hackableURLs
WithmostdeeplynestedresourcesifyouhavetheresourcesIDyoucanprobablyfigureouttheobjectsthatownitupthetree.
Inthiscaseyoucanhaveshort/simple/directurlslike:
/conversation{id}
/message{id}
e.g.sameresource:
/conversations/conversation{id}/messages/message{id}(whichimpliesthereisameaningfulpageat
/conversations/conversation{id}/messages,sayonethatlistedallmessagescf.todolists,foraconversation)
/conversations/conversation{id}/message{id}
/message{id}
ThesedirectURLsmaybeeasy/quick/handyforprogrammers.e.g.themakersoftheRESTfulservice,ordevelopersusingthe
RESTfulserviceasaclient.
Theyarenoteasilyhackablebyendusers.e.g.youcannotgofromthatdirecturltothecontainingresource.Sodonotusethem
inwhereyouwouldneedahackable/discoverable/endusereditableurl.
AsusualwhenthereisachoiceofURIsforasingleresourceselectyourcanonicalURIandreportitinyourresponse.
SomeRedRataconventions
Themainurlis/conversations/conversation{id}
ThereMAYbealinkonindividualconversationitems.e.g.thatgoesto/conversations/conversation{id}/message{id}
IFyouhaveapagethatshowsalistofmessagetypeitemsinaconversationhave/conversations/conversation{id}/messages
IFyouclickfromthatpagetoanindividualpagethenthatpagesurlSHOULDbe/conversations/conversation
{id}/messages/message{id}
ApparentlythethemeIamusingdoesnothaveusercommentsonpages,justposts,soifyouhaveanythoughtsonthispage
youllneedtomakeanycommentsoveronthisblogpost.
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 12/17
26Comments
Greg
PostedMay30,2012at10:02|Permalink
Thisisaveryinterestingandveygoodarticle!
IamwonderingthoughhowwecankeepthatniceURIdesignforatreestructure.
LetssayIwanttomanagesometaskslists.Eachlistcancontaintasksand/orotherlists(nodesandleavesinfact).
Iamthinkingabout3designs:
1)/lists/{id_list1}/lists/{id_list2}/lists/{id_list3}/tasks/{id_task1}
IamafraidthatsuchadesigncouldleadtoreallylongURIsifthetreehasalotoflevels.
2)/lists/{id_list1}/{id_list_or_task1}/{id_list_or_task2}/{id_list_or_task3}
Thisoneisshorterbutlessreadable.
3)/lists/{id_list_parent}/{id_list_or_task_child}
Thisoneisshortandcandescribethousandslevelstrees,butIfeellikesomethingsmissing
Whatwouldbeyouradvicebetweenthese3,orisitanothersmarterway?
DaniloRecchia
PostedJune13,2012at15:03|Permalink
Greatpost!
j0k
PostedJune18,2012at05:49|Permalink
Inadditiontothisarticle,hereisareallygoodpresentationbyDavidZuelkeabouthowdesigninghttpinterfaceandrestfulwebservice.
Pete
PostedJune18,2012at08:14|Permalink
Imgoingtopullawellactuallyhere,Iapologizeinadvance.Strictlyspeaking,aparticularURI/URLdesignhaslittletodowithRESTfulvs.NonRESTful.A
systemcanperfectlyadheretotheReSTconstraintswithURLslike/my/moppets/a/b/cdefaslongasthingslikestatelessness,HypermediaAsTheEnginesOf
ApplicationState(HATEOAS),etcasobserved.
AgoodURLdesigncertainlyhelpswithSEO,humanuserURLchangeslikefindingtheparentcollectionforaparticularitem,butletsnotconflatethatwithReST.
John
PostedJune18,2012at10:14|Permalink
TheresnosuchthingasRESTfulURIs.YoumaywanttogobackandreadRoysthesisbeforeyouthrougharoundtermslikethat.
Michele
PostedJune18,2012at11:08|Permalink
Icameacrossthisarticlethroughtwitter,hadnoIideawasboundtorimuhosting,ofwhichIhavebeenhappycustomerforyears
SaidthisImustsayIdonotunderstandallthisadversionforoldopaquequerystring.
Ithinkalsothatpathsarehierarchicalbynaturewhilecontextmightbenot.
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 13/17
ForexampletakeanEmployeethatbooksaRoomforameeting,inthebookingURLweneedbothareftotheEmployeeandtheRoom,whatwouldbethecorrect
pathforthisURLfollowingyourguidelines?Wouldyouforceorderonthesegments?Youwriteaboutnestedresourcesandlevelofnesting,butwhatisnestedin
what,inthiscase?
IthinkthatallURLarerestfulandformerestismoreaboutsendinglinkstochangestatetotheclients(asusuallyhappensinhtmlappsbutnotinsoap)thanbuilding
URIinsomewayorinanother.
OfcourseImightbewrong
PeterBryant
PostedJune18,2012at11:55|Permalink
ArestfulURIidentifiesaresource(cf.apage,orafunctionoraform).
Sointhecaseofanemployeebookingameetingroomtheresourceisthemeeting(theresourceisnottheroomortheemployee).
SocreateameetingwithaPOSTto/meetings/new(withformdatatoidentifyemployee,roomidandtime).Thenviewtheresourceat/meetings/meeting982john
room5
Michele
PostedJune18,2012at13:11|Permalink
HiPeter,
thanksfortheanswer.
SoifIgetitwell,querystringisokinthiscase.
Myextremistoldwayideawas:
insertBooking.do?room=3&employee=2
yours,ifIamcorrect,is
/bookings/new?room=3&employee=2
Thereisonepieceofinformationmoreinyour2segmentspathversionthatinmineislostinthepagename.Ofcourseismuchniceryourversionandthatpieceof
informationmorecanbeusedtohacktheuri.
SorryifIamlongandtakingtheoccasionofthisnicearticletomakequestionsaboutrestphilosophy,butwhatIamtryingtodiscoveristhis:areURI(s)writteninone
ortheotherwayreallyrelevantforfollowingrestarchitectureoraretheyjustaplus?
Iamtemptedtothinktheyarejustaplus,whatiseeessentialinsteadisthattheurirepresented*resource*mustbea_restresource_,soitmustexposetoclientsURI
representingotherresourcesallowingclienttoperformstatetransition,theniftheURIsarewritteninoneURIsyntaxortheotheritdoesnotmattersomuch.
Whatyouthinkaboutit,Iamgettingitright?
Thanks
MicheleVivoda
DavidZuelke
PostedJune19,2012at03:00|Permalink
InREST,itdoesnotmatterwhatyourURLslooklike,becauseallinteractionsaredriventhroughlinksandtheirrelations.
Or,inotherwords:youvelikelymissedtheHATEOAS/HypermediaaspectofREST,whichisthemostimportantpartoftheUniformInterfaceconstraint:
AlsoseeFieldingsmusingsonthematter,e.g.http://roy.gbiv.com/untangled/2008/restapismustbehypertextdriven
DavidZuelke
PostedJune19,2012at03:02|Permalink
Also,apageorafunctionoraformarenotresources,butmerely*representations*ofresources.Resourcesandtheirrepresentationsareconceptuallyseparate.Hence
*RepresentationalStateTransfer*.
Recommendedreading:RESTinPractice,areallygreatbookthatstepbystepteacheswhatRESTisabout(HypermediaandHATEOAS,notURIsorstatuscodesor
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 14/17
headers)andshowsthebenefitsofinfrastructurethatdoesntevenrelyonaspecificstructureforitsURLs(RESTisaboutdistributednetworkapplications,notabout
HTTPorwhateverelse).
PeterBryant
PostedJune19,2012at10:58|Permalink
+DavidZuelkeIagree:ARESTfulURIidentifiesaresource(ratherthanapage,orafunctionoraform).
ThisisanarticleaboutURIdesign.ParticularlyURIsthatmaybeusedinaRESTfulAPI.WhenyoubuildRESTfulapplicaitionsyoucanoftendoabetterjobofitif
youthinkcarefullyaboutthedesignofyourURIs.
Michele
PostedJune19,2012at12:11|Permalink
>InREST,itdoesnotmatterwhatyourURLslooklike,becauseallinteractionsaredriventhroughlinksandtheirrelations.
ThisiswhatIthought,isaplus.Iwillgiveatrytothebook,thanks.
IreadsometimeagothearticlefromFielding,butIliketoreaditagainfromtimetotime,stillnotgotitfully).
AmIgettingrightthatisessentialthatarepresentationofaresourceinarestarchitectureshouldprovidelinkstothepossibleactionsontheresourceorrelated
resources(applicationstatechanges)?
Michele
VicenteGallurValero
PostedJune20,2012at22:12|Permalink
Greatarticle,veryinterestingandwellexplained.TheonlysubjectIdontagreeisdroppingthelanguagefromtheURIforresourcesindifferentlanguages.
Iconsideratranslationadifferentresourceandnotarepresentationofthesamethinginotherformat,asusuallythetranslationispartial,localized,notexact,orsimply
doesntexist.
AlsoforpracticalreasonsIfindmoreusefulyoucanlinktheresourceinaconcretelanguage,asitgivesmorecontrolonwhatyouwanttolink,andtheuserclientmay
notshareanyofitsAcceptLanguageswiththeresourceslanguages.Youcanthenprovideadefaultlanguage,butcouldbeadifferentonetheoriginallinkerwanted
toshareandendingwithununderstandablecontent.
ForPUT,POSTandDELETE,altoughtyoucanspecifythelanguageonthebodyoftherequestIthinkitshouldgoontheURI,asyouaremodifyingjustthatlanguage,
Iseeitasadifferentresource.
DarrelMiller
PostedJune27,2012at17:16|Permalink
andjustonemoretime ThereisnosuchthingasaRESTfulURL.
AndIhavefoundthatdesigningbyURIdoesnotproducegreatresults.Itismuchbettertoidentifyresourcesandtherelationshipsbetweenthoseresources.Onceyou
havedonethat,pickingURIstoidentifythoseresourcesisusuallyprettytrivial.
SukantHajra
PostedSeptember6,2012at12:57|Permalink
Ibelievetheressomegoodadviceinthispost,buttheresalsounnecessarymisinformationinthebeginningaboutthedifferencebetweenURIs,URLs,andURNs.I
understandthatthishasbeenasourceofconfusionforsometime,butIthinkthedustissettling.Althoughwemaystilldebatewhatthesetermsmean,Ithinkwecanbe
moresureaboutwhatthesetermsdonotmean.
Herestheproblem.URIsarenotthetailpartofaURL.URLsareatypeofURI,asareURNs.URLsaredesignedmoreforresolving.
TheWikipediapageaboutthisisnottoobad.Butincaseyourelookingforamoreofficialopinion,theW3issuedaniceretrospectivereporttohelpclarifythematter.
Itdoesntresolveallconfusion,butitdoesagoodjobacknowledginghowsemanticshavemorphedastheinternethasmorphed.
DanielHalperin
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 15/17
PostedDecember7,2012at13:52|Permalink
HiPeter,
Helpfularticle.IwonderifyouhaveanyintuitiononhowtheparsercodefortheseURIsworks.Forinstance,inJAXRSyouannotateeachclassandfunctionwiththe
paththatshouldcallit.SotheclassrepresentingaConversationresourcemightbeannotatedwith@Path("/conversations").Thefunctionthathandlesan
individualconversationwouldbeannotatedwith@Path("conversation-{conversationId}").
IfthereisanalternateURIto,e.g.,/messages/message-1/conversations/conversation-1howwouldtheannotationstructureswork?Itwouldseemcomplicated
anderrorpronetopredictallpossiblecombinationsofURIstoputthesamefunctionsineveryresource.
Howdoyoudesignyourparsers?
PeterBryant
PostedDecember7,2012at14:03|Permalink
Itisprobablybesttoavoiddifferentpathswherepossible.AndjustuseasingleURIforeachresource.
e.g.Idargueaconversationincludesamessagebutnotviceversa.
AsfarastheparsinggoesIhaveaclassperresource.For@PathannotationsIreturnaninstanceoftheappropriatejaxrsclass.TheJAXRSclassrepresentstheresource.it
doesnthavetocareaboutthepaththeusertooktoreachit.
Makesense?
DanielHalperin
PostedDecember8,2012at08:04|Permalink
Peter,
Thanksforthereply.
Inyourexamples,youoftenhavemultiplewaystogettothesameresource.Areyounowsayingthatweshouldntdothat?
Inanycase,withaGooglesearchinspiredbyyourmessage,IfoundtheSubresourcestechniquedescribedhere,whichseemstoanswermyquestion.
Thankssomuch!
Dan
JV
PostedDecember17,2012at05:11|Permalink
Hi,
Greatarticle.
IwhanttoaskyouropinionaboutURIDesign.
IneedtodevelopaRESTAPIandIhavedoubtsabouttheURIdesign.
Scenario:
1ImdevelopingoneRESTinterfacetoasetofservices.
2eachserviceisdividedfromthelogicalpointofviewinseveralparts(notresources).
3eachresourcecanbeaccessedintwowaysAandB
WhatisthemostappropriateURIdesign?
/service1/part1/resource?{A|B}
/service1,part1,resource?{A|B}
espinete
PostedMarch12,2013at01:37|Permalink
Forseparatingparameters,aresemicolonsbetterthanampersands?
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 16/17
Frogblatterbeast
PostedApril23,2013at20:28|Permalink
WhileIunderstandthatRESTisntspecificaboutURIdesign,Icompletelyagreethatgood,semanticURIdesignisimportantforagoodwebapplication,justas
everyonetakesitforgrantedthatfunctions,classesandcompilationunitsintraditionalsoftwareengineeringaregivenreadableanddescriptivenames.Itreallydoesnt
matterthatmuchwhethertheURIisconsumedbyahumanoramachine.IfyouspendsometimethinkingaboutyourURIdesign,youwillmostcertainlyendupwitha
betterandmorebusinessdrivenapplicationdesign.
DougMoscrop
PostedJune16,2013at03:12|Permalink
ThisisanarticleaboutURIdesign.ParticularlyURIsthatmaybeusedinaRESTfulAPI.WhenyoubuildRESTfulapplicaitionsyoucanoftendoa
betterjobofitifyouthinkcarefullyaboutthedesignofyourURIs.
URIdesignisanoxymoronserversneedtocontroltheirnamespaces,andhierarchyhasnomeaning.IdontdisagreewithreadableURIs,butthatspurelyfor
humanbeingstomuckabout.FromanAPIperspective,fromafunctionalperspective,everyresourcecouldbemountedviasomeGUIDandyourestillasREST(ornot)
asyouarewithwelldesignedURIsyntax.
Youshouldhavewrittenanarticleonrelationshipdesignbecausethatsakeypartofhypermediabasedstatetransition.
e.g.Idargueaconversationincludesamessagebutnotviceversa.
Thisisincrediblyfaroffthepoint.YouretryingtothinkaboutyourdomainandyourdomaindoesnotpresentitselfdirectlythroughyourAPIwhatmattersisstate
transition.Fromarepresentationofagivenresource,whataremypossiblestatetransitions?Youneedtoexpressthoseashyperlinks.Aconversationcouldbea
collectionlikeresourceofhyperlinkstoindividualmessages.Thosemessageshavehyperlinkstoo.Whatlinks?Well,thatstheimportantpartofthedesign.Thepart
youseemtohaveglossedover.
JohnPaul
PostedJuly16,2013at17:50|Permalink
NiceinformationaboutURInaming
CalebCushing
PostedMarch17,2014at08:01|Permalink
ImcurioushowUsingvendorspecificAcceptheadershasworkedout?Imlookingatthatforasolutiontothis
http://programmers.stackexchange.com/q/232556/2331
CalebCushing
PostedMarch17,2014at09:14|Permalink
answerstothisquestionaboutwhetherhttpclientscheckthemimetypewhendeterminingtouseacachedresponseseemsrelevant,iftheydontthenusingthesameuri
withdiffernentmimetypeswouldntreallyworksafely,asthecacheshouldgiveyouthesameresponseregardlessofanewmimetype
http://stackoverflow.com/q/22441874/206466
DaveSchinkel
PostedApril9,2014at07:50|Permalink
@DavidZuelke
Wrong,andthisisthekindofhalfbakecowboydriventhinkingthatdrivesmecrazywithsomepeople(nooffenseDavidbutIjusthadtosaythis).
ThisislikeanalogytosaywedoTDDbutwefeelwecanskipthebluestepinTDDattimes.
TheURImattersasittiestoaRESOURCE,soitsalltiedintoRESTandinhowyouoveralldesignyourRESTfulAPI.TheURItellstheserverwhatresourceits
lookingforandtheconventionMATTERSyoumaydoitslightlydifferentbutforthemostparttheresaprettyconsistentpatternpeoplefollowwithRESTfulURIs.
WhatifyourecodingforexampleASP.NETMVC.YouwouldwantyourURLstostillrequestresourcesandyourroutetabletobindthosetospecificcontrollersfor
processing.HowcanyoudothatifyoudonthaveapatternthatpromotesRESTinyourURL?meaningyourerepresentingresources!(insteadofRPCstyle).
SurehypermediaiscriticalintheresponsebutyoudonttakeouttheURIpartsayingitsnotcriticalorsomehowdoesntrelateormattertoREST.
5/23/2014 REST-ful URI design | 2PartsMagic Blog
http://blog.2partsmagic.com/restful-uri-design/ 17/17
The2PartsMagicwritersworkonthecoalfaceofwebbased,softwareasaservice,Javafocuseddevelopers.Theyworkonsiteslike:
InboxHarmony,thecollaborativeemailclientforsupportteams
RimuHostingdedicatedservers
RimuHostingVPSservers
ZonomiDNShosting
Pingabilitywebsitemonitoringandalertservice
Bakop,FTPbasedoffsiteserverbackups
Bloggingoncustomerservice
2Trackbacks
ByRESTfulURIDesign:verbsvs.resourcenounsonApril25,2009at18:22
ByBraartikelomRESTfulURI:sStacktrace.seonApril19,2010at22:27
PostaComment
Youremailisneverpublishednorshared.Requiredfieldsaremarked*
Name*
Email*
Website
Comment
YoumayusetheseHTMLtagsandattributes<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del
datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre lang="" line="" escaped="" cssfile="">
PostComment
SecurityQuestion:
Whatis2+4?
IMPORTANT!Tobeabletoproceed,youneedtosolvethefollowingsimplemath(soweknowthatyouareahuman):)