le design d’api rest, un débat sans finjavaetmoi.com/wp...france...rest_un_debat_sans_fin.pdfle...

Ledesignd’APIREST,undébatsansfin?Speaker:GuillaumeLaforge(Restlet)Format:ConférenceDate:22avril2016Restletproposeplusieursproduits:Studio,APISpark,Framework,DHC

RoyFieldingadéfiniRepresentationalStateTransfer:

• Identificationdesresources:URIs• Représentation:JSON,XML• Self-descriptivemessage:http,GET,cacheability• HAETOAS

Lesverbespermettentdetravailleràlafoissuruneressourceouunelistederessources.PasdePOSTpourunitemmaissurlaliste.NommagePourlesressources,privilégiezl’usagedesnomsplutôtquedesverbes(différentsqu’enSOAP).Lesverbespeuventêtreutiliséspourlesactionsoulescalculs:/login,/convertTemperaturePréférezl’usagedupluriel.Ex:/tickets/234Permetdes’affranchirdesformessingulières/pluriel:/personvs/peopleJeveuxle234ièmeélémentdelacollectionticketsFormedenommage:UpperCamelCase,lowerCamelCase,snake_case,dashed-nake-caseQuestiondegoût.Choisirunenormeetrestercohérent

GestiondesrelationsNotiondesous-ressources:/tickets/123/messages/4Lorsqu’uneressourceestindépendante,avoirsapropreurl.Ex:/usergroups/24/users/12=>/users/12Paramètresd’APIPasderèglesengénéral.CellesutiliséeschezRestlet:

• Path:Required,resourceidentifier• Query:optional,querycollections(ex:pagination)• Body:resourcespecificlogic• Header:global,platform-wide(ex:APIKeys)

HTTPStatusCode

• 4xx:leclientdel’APIafaituneerreur• 5xx:erreurcôtéserveur• Lorsdelapagination,onpourraitutiliser206partialcontent+Link:danslesheaders

pourlesURLprev/net• Lorsdelacréationd’unenouvelleressource,renvoyerun201createdavecleheader

Location• Lorsd’untraitementasynchrone,onpeutrenvoyer202Accepted(nopayload

returned)• AprèsunDELETE,retourner204Nocontent

Anti-pattern:Facebookrenvoietoujours200OKmêmeencasd’erreurAPINavigationDémoavecDHCetl’APIStarwarsCachingEtagavecleshashtagOuNot-Modified-SincePaginationEnparamètrederequêtesHTTP:Pagenumber:?page=23,Avecdescurseurs:?cursor=34ea3fd6(insertion-friendly)pournepasraterdesélémentsPaginationparattribut

Raremaisélégant:AcceptrangeheadernotjustforbytesGET/usersAccept-Ranges:usersContent-Raneusers0-9/200CollectionsPréférerlesunwrappedcolllctionàlaplacedesdonnées(objetintermédiairedata),celapermetderajouterdesméta-donnéesErreursStandardisationencoursducontenudelaréponsed’erreur(cf.photoci-dessus).SiuneAPIretourneuncoded’erreur4xxxxnonsupportéparleclient,cedernierdoitletraitercommeuneerreurgénérique400.FilteringLesbesoinsmobilesetwebpeuventdifférer.Onpeutfiltrelesdonnéesqu’onsouhaiterécupérer.Aveclesqueryparameters:?fields=firstname,lastname,age?exclude=biography,resyle?style=compactAvecleheaderpreferPrefer:return=minimalUtilisationducaractèrepoint.pourrécupérerlesous-champs:?fields=adress.zipTri

• SQL-style:?sort=title+DESC• Sort+asc/descCOMBO

Recherche/Filter/sortAPIpermettantauclientderécupérercequ’ilssouhaitent:Facebook’sGraphQLNetflix’sFalcor

Versionningd’API

• Leplusfréquentdansl’URL:v1• CustomHeader:X-API-Version:2• SurGitHub:MimeTypeaveclaversion

HyperMediaRichardsonadéfinitunmodèledematurité.Ledernierniveau,lelevel3concerneleHypermediaControls.Avantages:

• Clientsplusgénériques• Plusbesoindeversionnersystématiquementl’API,parexempleunchangement

d’URLd’uneressourceInconvénients:

• Réponsepluslourde(terminauxmobilesetmauvaiseconnexion)• Lesclientsdoiventconnaîtreàquoicorrespondantlequalificatifdulienretourné

Pleind’approches:HAL,JSON-LD…AvecHAL,onajouterunattribut_linksIdentifiantsUtiliserlesUUIDàlaplacedesidentifiantsséquentielsQuestions/Réponses

• VerbePATCH:miseàjourpartielle(ex:unseulchamps).RegarderJSON-PATCHpourfairedesdiffentrelespayloads