Your SlideShare is downloading. ×
Iasi code camp 20 april 2013 designing res tfull webservices and web apis - remus pereni
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Iasi code camp 20 april 2013 designing res tfull webservices and web apis - remus pereni

178

Published on

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
178
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
5
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide
  • API-urile nu exista de sine independent, in izolatie. API-urile expun un set de functionalitati ale unei aplicatii sau serviciu care exista in mod identependent de existenta API-ului. Din acest punct de vedere rolul unui designer de API REST sunt:1. Sa inteleaga suficiente detalii din aplicatia ale carei servicii urmeaza sa le expuna pentru a putea lua o decizie informata in privinta carei functionalitati trebuie expusa, cum poate fi expusa si ce poate fi lasat afara2. Sa modeleze aceasta functionalitate intr-un API care sa adreseze toate cerintele unei utilizari urmarind cit mai aproape principiile RESTExista 3 actorii in aceasta piesa1. Aplicatia2. API-ul3. Clientul
  • Daca am concepe URI-urile in still RPC (procedural) ar iesi un API / metode stufioae si non intuitive.Asa nu.
  • Sa le organizăm un pic.Colecții: Sunt de fapt liste de obiecte / resurse care ne intereseaza. Operatii asupra lor pot sa permita crearea unei resurse noi in colectie sau nu respectiv stergerea tuturor resurselor sau nuStore-uri: Este o colectie gestionata de catre client. In esenta ele nu creaza resurse independente, doar le colecteazaDocument-ul: Reprezintă resursa in sine cea care este gestionată propriuzis (de exemplu proiectele, clientii, entry-urile de date, samd
  • Sa le organizăm un pic
  • Asa da
  • Sa le organizăm un pic
  • Asa da
  • Sa le organizăm un pic.Colecții: Sunt de fapt liste de obiecte / resurse care ne intereseaza. Operatii asupra lor pot sa permita crearea unei resurse noi in colectie sau nu respectiv stergerea tuturor resurselor sau nuStore-uri: Este o colectie gestionata de catre client. In esenta ele nu creaza resurse independente, doar le colecteazaDocument-ul: Reprezintă resursa in sine cea care este gestionată propriuzis (de exemplu proiectele, clientii, entry-urile de date, samdControlere: Modeleaza concepte procedurale, actiuni care nu se pot mapa pe operatiile traditionale CRUD
  • Sa le organizăm un pic
  • Fiti consistenti
  • Folositi forward slash separator (/) indica relatii hierarhice
  • Transcript

    • 1. Occasion:Date:Present:Classification:Designing RESTfullWebServices and Web APIsBest PracticesCodeCamp Iasi20-04-2013Remus Pereni / Software Architect / remus.pereni@tss-yonder.comPublic
    • 2. 2Software ArchitectTSS-YonderWeb & Mobile Web & JavaTwitter: @remuspereniWeb: http://remus.pereni.orgRemus PereniYonder Romaniahttp://tss-yonder.com@tssyonderCluj NapocaCalea Dorobantilor 18-20 PowerBusiness CenterIasiSos. Pacurari 138
    • 3. Evolutie31995De ce avemnevoie de Website?2000 2005 2013Bineinteles avemwebsite!Bineinteles caavem un API!De ce avemnevoie de API?
    • 4. 4Evolutie API-uriTotal APIs over time
    • 5. Evolutie API-uri5Total APIs over time
    • 6. REST vs. SOAP: Simplicity wins again6Distribution of API protocols and stylesBased on directory of 3,200 web APIs listed at ProgrammableWeb, May 2011
    • 7. 7Componente
    • 8. 8● https://api.taskmgm.com/createCompany● https://api.taskmgm.com/deleteCompany● https://api.taskmgm.com/getCompany● https://api.taskmgm.com/getAllCompanies● https://api.taskmgm.com/getAllProjects● https://api.taskmgm.com/getProject● https://api.taskmgm.com/createProject● https://api.taskmgm.com/updateProject● https://api.taskmgm.com/deleteProject● https://api.taskmgm.com/createLog● https://api.taskmgm.com/updateLog● https://api.taskmgm.com/deleteLog● https://api.taskmgm.com/getLogs● https://api.taskmgm.com/getLogResurse Web
    • 9. 9/{colecții}conțin->/{store-uri}care stocheză->/{documente}care au datelepropriuziseResurse Web
    • 10. 10/companies- colectie- lista de companii/1234- document- detalii companie 1234Resurse Web
    • 11. 11● https://api.taskmgm.com/v1/companies● https://api.taskmgm.com/v1/companies/1234● https://api.taskmgm.com/v1/projects● https://api.taskmgm.com/v1/projects/1234● https://api.taskmgm.com/v1/logs● https://api.taskmgm.com/v1/logs/12182Resurse Web
    • 12. 12/projects- colectie- lista deproiecte/favorites-un store-returneaza toto listă-cu proiectelefavorite/1234- document- detalii proiectfavoritResurse Web
    • 13. 13● https://api.taskmgm.com/v1/projects● https://api.taskmgm.com/v1/projects/1234● https://api.taskmgm.com/v1/projects/favorites● https://api.taskmgm.com/v1/projects/favorites/1234Resurse Web
    • 14. 14/{colecții}conțin->/{store-uri}carestocheză->/{documente}care audatelepropriuzise/{controlere}modeleazaun conceptproceduralResurse Web
    • 15. 15/users- colectie- lista deutilizatori/1234- document- detalii unuianumit user/resetPassword-controlerreseteazaparolaResurse Web
    • 16. 16● https://api.taskmgm.com/v1/users● https://api.taskmgm.com/v1/users/1234● https://api.taskmgm.com/v1/users/1234/resetPassword● https://api.taskmgm.com/v1/users/loginResurse Web
    • 17. 17Resursă POSTCreazăGETCiteștePUTActualizeazăDELETESterge/companies 201 CreatedCrează o nouăcompanie200 OKObtine lista decompanii405 MethodNot Allowedsau 200 OKActualizeazatoată lista decompanii405 MethodNot Allowedsau 200 OKNimic sauSterge toatalista decompanii/companies/1234405 MethodNot Allowedsau404 NotFound200 OKObtine detaliidesprecompania1234200 OKDaca existacompania1234actualizeazaaltfel erroare:404 NotFound200 OKStergecompania1234sau 404 NotFound dacanu existăOperații asupra resurselor / Metode HTTP
    • 18. 18● RFC 3986● Syntaxa unui URI e:o schemeo "://"o authorityo "/" patho [ "?" query ]o [ "#" fragment ]● http://example.com/v1/users#name?q=RemusURI
    • 19. 19● Folositi substantive la plural si nu verbeo /companieso /userso /getUserso /getCompanies● Nu amestecati plural si singular, nu econsistento /companieso /usero /usersURI / Best practice-uri
    • 20. 20Utilizati charactere mici in URI-uri (lowercase)● https://api.taskmgm.com/v1/userso o resursa● HTTP://Api.Taskmgm.com/v1/userso aceiasi resursa ca mai sus● https://api.taskmgm.com/v1/Userso o alta resursaDe ce?RFC 3896 defineste URI-urile case sensitive exceptind Protocol-ul sicomponentele host-uluischeme "://" authority "/" path [ "?" query ] [ "#" fragment ]URI / Best practice-uri
    • 21. 21Nu includeti extensie de fisiere in URI-uri● https://api.taskmgm.com/v1/users/1234.jsonMecanismele HTTP pentru negocierea continutuluiHeadereleo ACCEPTo ContentTypeURI / Best practice-uri
    • 22. 22● Forward slash separator (/) indicarelatii hierarhiceo http://example.org/vinzari/2012/08/01URI / Best practice-uri
    • 23. 23● Trailing forward slash (/) nu trebuie sa termine unURIo http://example.org/companies/1234/o http://example.org/companies/1234● De ce?o Nu adauga valoare semanticao Poate cauza confuzie (2 uri-uri diferite trebuie sa identifice2 resurse diferite)URI / Best practice-uri
    • 24. 24Hypens (-) pot fi folosite pentru a imbunatatiireadability-ul URI-urilorhttp://example.org/blogs/remus-pereni/entry/primul-postURI / Best practice-uri
    • 25. 25Underscore (_) nu ar trebui folositeLink-urile de obicei sunt afisate cu underline siatuncea underscore poate fi confundatURI / Best practice-uri
    • 26. 26● Folosit pentru a obtine starea unei resurse● Cererea poate contine headere dar nubody● Cereri repetate la GET nu e voie sa aibaefecte secundare / duca la modificari destare● Cache-urile depind de abilitatea de a serviun raspuns fara a mai contacta serveruloriginalMetode HTTP / GET
    • 27. 27● Exact ca si GET, returneaza doar headerelefara body● Folosit la verifica existenta unei resurse saua metadatelor legat de eaMetode HTTP / HEAD
    • 28. 28● Folosit pentru insert si update-uri● Mesajul trebuie sa contina oreprezentare a resursei pe care clientuldoreste sa o stocheze pe server● Continutul mesajului poate sa nu fieidentic cu cea ce ar primi de la unrequest GET. Poate contine doar valorilemutabile / variabile din starea resursei● Operatiune IdempotentaMetode HTTP / PUT
    • 29. 29● Folosit pentru a crea o resursa noua intr-ocolectie● Folosit pentru a invoca controleri● Permis pentru orice actiune fara legatura curepetabilitatea sau efectele colaterale(unsafe & non-idempotent)● Nu este garantata repetabilitatea● A nu se folosi pentru a obtine / sterge /actualiza resurseMetode HTTP / POST
    • 30. 30● Folosita pentru a sterge o resursa dintr-o colectie● O data stearsa cu DELETE resursa numai trebuie sa apartina colectiei (oriceGET sau HEAD pe resursa respectivatrebuie sa se termine cu 404 NOTFOUNDMetode HTTP / DELETE
    • 31. 31● Folosita pentru a sterge o obtine lista deoperatii posibile asupra unei resurse● Allow: GET, PUT, DELETEMetode HTTP / OPTIONS
    • 32. 32● Mai multe abordario Versiune in path• http://example.com/timetrack/v1/companies/yondero Versiune in header● Versiune in header / parte din negocierio Un URI trebuie sa identifice constant o resursao Modificarea URI-ului presupune o resursa nouao Deci V1 & V2 denota 2 resurse diferite -> IncorectVersionarea serviciilor
    • 33. 33● Ascundeti complexitate in spate la ?o https://api.taskmgm.com/v1/companies?limit=10&offset=0● Puteti folosi limit și offset● Să aveți valori implicite pentru elePaginare
    • 34. 34● Implicit parte din HTTP● header-ul: AcceptAccept = "Accept" ":"#( media-range [ accept-params ] )media-range = ( "*/*"| ( type "/" "*" )| ( type "/" subtype )) *( ";" parameter )accept-params = ";" "q" "=" qvalue *( accept-extension )accept-extension = ";" token [ "=" ( token | quoted-string ) ]Accept:text/html,application/xhtml+xml,application/xml;q=0.9,*/*;https://api.taskmgm.com/v1/companies?format=jsonFormate multiple
    • 35. 35Fie prin controllerhttps://api.taskmgm.com/v1/companies/searchAscundeti complexitate in spate la ?https://api.taskmgm.com/v1/companies?search=YonderCautare
    • 36. 36Coduri de răspuns, tratarea exceptiilorHttp status code : 401 Unauthorized● {o “developerMessage” : “Verbose, plain language description ofthe problem for the app developer with hints about how to fixit.”o , “userMessage”:”Pass this message on to the app user ifneeded.”o , “errorCode” : 12345o , “more info”: http://dev.teachdogrest.com/errors/12345● }
    • 37. 37Success Totul afuncționatErroareclientAplicatia afacut cevagreșitErroareserverUps s-aintinplatceva aiureaCoduri de răspuns, tratarea exceptiilor
    • 38. 38● HTTP Defineste 5 categoriiCoduri de răspuns, tratarea exceptiilor1XX Informational Comunica informatii la nivel de protocol2XX Success Cererea clientului acceptata cu success3XX Redirectari Indica ca sunt nevoie actiunisuplimentare pentru a complectarequestul4XX Errori client Erroare datorata in general request-ului/ Clientului5XX Errori server Erroare datorata in general serverului
    • 39. 39Success 200 OKErroareclient400 BadReuestErroareserver500 InternalServer ErrorCoduri de răspuns, tratarea exceptiilor
    • 40. 40Coduri de răspuns, tratarea exceptiilor
    • 41. 41Creare 201 CreatedResursagresita404 NotFoundLipsaautorizații401UnauthorizedMetodane-permisa403ForbiddenCoduri de răspuns, tratarea exceptiilor
    • 42. 42● 200 (“OK”)o Codul pe care clientii spra sa-l vadao Indica successo In general trebuie sa includa un raspuns in bodyo Nu trebuie folosit in a comunica errori in continutul mesajului● 201 (“Created”)o Folosit de cite ori o colectie sau un store creaza o resursa nouabazat pe cererea clientuluio Poate fi si raspuns al apelului unui controller in cazul in care oresursa este creata● 202 (“Accepted”)o Folosit pentru raspunsuri asincroneo O operatiune lunga a fost inceputa, pare valida dar poate incagenera errorio In general folosit la controlereCoduri de răspuns, tratarea exceptiilor
    • 43. 43● 204 (“No Content”)o Operatia e reusita dar nu exista continut de returnat(DELETE, de exemplu)● 301 (“Moved Permanently”)o Resursa s-a mutat si exista o noua locatie pentru eao Locatia se trimite ca parte a Location header-ului● 303 (“See Other”)o Controler-ul si-a terminat treaba dar in loc sa trimita un raspunspotential nedorit poate trimite in Location un URI la o resursacare poate prezenta interes pentru clienti● 304 (“Not Modified”)o Similar cu 204 (“No Content) in sensul ca body-ul e golo Clientul are deja cea mai recenta versiuneo Folosit impreuna cu alte headere ce determina HTTPConditionaleCoduri de răspuns, tratarea exceptiilor
    • 44. 44● 400 (“Bad Request”)o Mesaj de erroare generic cind nici un alt 4xx nu este potrivito Raspunsul poate contine body cu mesaj detaliat legat de erroare● 401 (“Unauthorized”)o Nu are authorizarea necesara sau nu a asigurat nici un fel deauthorizare● 403 (“Forbidden”)o Indica ca request-ul e corect dar backend-ul refuza sa-l onorezeo Nu este o problema de autorizare (ar fi 401), poate clientul nuare permisiunea de a apela acea parte din API● 404 (“Not Found”)o Cererea nu poate fi mapata pe o resursa● 405 (“Method Not Allowed”)o Daca clientul a incercat o operatie ne-permisa (ex: DELETE pe oresursa read only)o Trebuie sa se trimita inapoi header-ul Allow: GET, POST cumetodele suportateCoduri de răspuns, tratarea exceptiilor
    • 45. 45● 406 (“Not Acceptable”)o Formatul cerut de client nu este suportat (Ex. clientul cereapplication/xml prin intermediul headerului Accept dar serverulare pregatit doar application/json● 409 (“Conflict”)o Daca se incearca punerea unei resurse intr-o stare inconsistentao Ex, se incearca stergerea unei colectii care nu e goala● 415 (“Unsuported Media Type”)o Indica ca serverul nu poate parsa cererea in formatul descris deheader-ul Content-Typeo Ex. Body-ul contine application/xml dar serverul stie sa tratezedoar application/json● 500 (“Internal Server Error”)o Probleme pe partea de server, ex exceptii aruncate si ne tratateCoduri de răspuns, tratarea exceptiilor
    • 46. 46ResurseWeb API Design?Crafting Interfaces that DevelopersLoveBy Brian MulloyEbook gratuit oferit de apigeehttp://apigee.com/about/content/web-api-design
    • 47. 47ResurseREST API Design RulebookDesigning Consistent RESTfulWeb Service InterfacesBy Mark MassePublisher: OReilly MediaReleased: October 2011Pages: 116
    • 48. 481. Atlassian REST API Design Guidelines version 1https://developer.atlassian.com/display/DOCS/Atlassian+REST+API+Design+Guidelines+version+12. Thoughts on RESTful API DesignLessons learnt from designing the Red Hat Enterprise Virtualization APIhttps://restful-api-design.readthedocs.org/en/latest/Resurse
    • 49. 49Întrebări?photo cc by http://www.flickr.com/photos/horiavarlan/4273168957/
    • 50. 50Thank You !Please fill the evaluation form slidephoto cc by http://www.flickr.com/photos/wwworks/4759535950/

    ×