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

357 views

Published on

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

  • Be the first to like this

No Downloads
Views
Total views
357
On SlideShare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
7
Comments
0
Likes
0
Embeds 0
No embeds

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
  • Iasi code camp 20 april 2013 designing res tfull webservices and web apis - remus pereni

    1. 1. Occasion:Date:Present:Classification:Designing RESTfullWebServices and Web APIsBest PracticesCodeCamp Iasi20-04-2013Remus Pereni / Software Architect / remus.pereni@tss-yonder.comPublic
    2. 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. 3. Evolutie31995De ce avemnevoie de Website?2000 2005 2013Bineinteles avemwebsite!Bineinteles caavem un API!De ce avemnevoie de API?
    4. 4. 4Evolutie API-uriTotal APIs over time
    5. 5. Evolutie API-uri5Total APIs over time
    6. 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. 7. 7Componente
    8. 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. 9/{colecții}conțin->/{store-uri}care stocheză->/{documente}care au datelepropriuziseResurse Web
    10. 10. 10/companies- colectie- lista de companii/1234- document- detalii companie 1234Resurse Web
    11. 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. 12/projects- colectie- lista deproiecte/favorites-un store-returneaza toto listă-cu proiectelefavorite/1234- document- detalii proiectfavoritResurse Web
    13. 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. 14/{colecții}conțin->/{store-uri}carestocheză->/{documente}care audatelepropriuzise/{controlere}modeleazaun conceptproceduralResurse Web
    15. 15. 15/users- colectie- lista deutilizatori/1234- document- detalii unuianumit user/resetPassword-controlerreseteazaparolaResurse Web
    16. 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. 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. 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. 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. 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. 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. 22● Forward slash separator (/) indicarelatii hierarhiceo http://example.org/vinzari/2012/08/01URI / Best practice-uri
    23. 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. 24. 24Hypens (-) pot fi folosite pentru a imbunatatiireadability-ul URI-urilorhttp://example.org/blogs/remus-pereni/entry/primul-postURI / Best practice-uri
    25. 25. 25Underscore (_) nu ar trebui folositeLink-urile de obicei sunt afisate cu underline siatuncea underscore poate fi confundatURI / Best practice-uri
    26. 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. 27● Exact ca si GET, returneaza doar headerelefara body● Folosit la verifica existenta unei resurse saua metadatelor legat de eaMetode HTTP / HEAD
    28. 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. 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. 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. 31● Folosita pentru a sterge o obtine lista deoperatii posibile asupra unei resurse● Allow: GET, PUT, DELETEMetode HTTP / OPTIONS
    32. 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. 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. 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. 35. 35Fie prin controllerhttps://api.taskmgm.com/v1/companies/searchAscundeti complexitate in spate la ?https://api.taskmgm.com/v1/companies?search=YonderCautare
    36. 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. 37. 37Success Totul afuncționatErroareclientAplicatia afacut cevagreșitErroareserverUps s-aintinplatceva aiureaCoduri de răspuns, tratarea exceptiilor
    38. 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. 39. 39Success 200 OKErroareclient400 BadReuestErroareserver500 InternalServer ErrorCoduri de răspuns, tratarea exceptiilor
    40. 40. 40Coduri de răspuns, tratarea exceptiilor
    41. 41. 41Creare 201 CreatedResursagresita404 NotFoundLipsaautorizații401UnauthorizedMetodane-permisa403ForbiddenCoduri de răspuns, tratarea exceptiilor
    42. 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. 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. 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. 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. 46. 46ResurseWeb API Design?Crafting Interfaces that DevelopersLoveBy Brian MulloyEbook gratuit oferit de apigeehttp://apigee.com/about/content/web-api-design
    47. 47. 47ResurseREST API Design RulebookDesigning Consistent RESTfulWeb Service InterfacesBy Mark MassePublisher: OReilly MediaReleased: October 2011Pages: 116
    48. 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. 49Întrebări?photo cc by http://www.flickr.com/photos/horiavarlan/4273168957/
    50. 50. 50Thank You !Please fill the evaluation form slidephoto cc by http://www.flickr.com/photos/wwworks/4759535950/

    ×