Le design d’API REST, un débat sans fin ? Speaker : Guillaume Laforge (Restlet) Format : Conférence Date : 22 avril 2016 Restlet propose plusieurs produits : Studio, APISpark, Framework, DHC Roy Fielding a défini Representational State Transfer : • Identification des resources : URIs • Représentation : JSON, XML • Self-descriptive message : http, GET, cacheability • HAETOAS Les verbes permettent de travailler à la fois sur une ressource ou une liste de ressources. Pas de POST pour un item mais sur la liste. Nommage Pour les ressources, privilégiez l’usage des noms plutôt que des verbes (différents qu’en SOAP). Les verbes peuvent être utilisés pour les actions ou les calculs : /login, /convertTemperature Préférez l’usage du pluriel. Ex : /tickets/234 Permet de s’affranchir des formes singulières / pluriel : /person vs /people Je veux le 234 ième élément de la collection tickets Forme de nommage : UpperCamelCase, lowerCamelCase, snake_case, dashed-nake-case Question de goût. Choisir une norme et rester cohérent
Welcome message from author
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
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
Related Documents
