Designing RESTfull     WebServices and Web APIs                                                Best Practices    Occasion:...
Remus PereniSoftware Architect             Yonder RomaniaTSS-Yonder                      http://tss-yonder.com            ...
Evoluție	  API-­‐uri	   De ce avem                Bineinteles avem    De ce avem      Bineinteles canevoie de Web         ...
Evoluție	  API-­‐uri	  From Open APIs: State of the Market by John Musser, ProgrammableWeb                                ...
Evoluțe	  API-­‐uri	  From Open APIs: State of the Market by John Musser, ProgrammableWeb                                 ...
REST	  vs.	  SOAP:	  Simplicity	  wins	  again	  From Open APIs: State of the Market by John Musser, ProgrammableWeb      ...
Componente             8
Resurse Web●    https://api.taskmgm.com/createCompany●    https://api.taskmgm.com/deleteCompany●    https://api.taskmgm.co...
Resurse Web/{colecții}              /{store-uri}conțin->                                /{documente}              care sto...
Resurse Web/companies                      /1234- colectie- lista de companii   - document                      - detalii ...
Resurse Web●  https://api.taskmgm.com/v1/companies●  https://api.taskmgm.com/v1/companies/1234●  https://api.taskmgm.com/v...
Resurse Web/projects             /favorites- colectie                               /1234- lista de   -un storeproiecte   ...
Resurse Web●  https://api.taskmgm.com/v1/projects●  https://api.taskmgm.com/v1/projects/1234●  https://api.taskmgm.com/v1/...
Resurse Web/{colecții}              /{store-uri}conțin->                             /{documente}              care       ...
Resurse Web/users              /1234- colectie                               /resetPassword- lista de    - documentutiliza...
Resurse Web●  https://api.taskmgm.com/v1/users●  https://api.taskmgm.com/v1/users/1234●  https://api.taskmgm.com/v1/users/...
Operații asupra resurselor / Metode HTTPResursă       POST            GET              PUT               DELETE           ...
URI, definiție●  RFC 3986●  Syntaxa unui URI e:  o  scheme  o  "://"  o  authority  o  "/" path  o  [ "?" query ]  o  [ "#...
URI / Best practice-uri●  Folositi substantive la plural si nu verbe  o  /companies  o  /users  o  /getUsers  o  /getCompa...
URI / Best practice-uriUtilizati charactere mici in URI-uri (lowercase)●  https://api.taskmgm.com/v1/users   o  o resursa●...
URI / Best practice-uriNu includeti extensie de fisiere in URI-uri●  https://api.taskmgm.com/v1/users/1234.jsonMecanismele...
Formate multiple●  Implicit parte din HTTP●  header-ul: Accept	  Accept	  	  	  	  	  	  	  	  	  =	  "Accept"	  ":"	  	  ...
URI / Best practice-uri●  Forward slash separator (/) indica   relatii hierarhice  o http://example.org/vinzari/2012/08/01...
URI / Best practice-uri●  Trailing forward slash (/) nu trebuie sa termine un   URI   o  http://example.org/companies/1234...
URI / Best practice-uriHypens (-) pot fi folosite pentru a imbunatatiireadability-ul URI-urilor   http://example.org/blogs...
URI / Best practice-uriUnderscore (_) nu ar trebui folosite  Link-urile de obicei sunt afisate cu underline si  atuncea un...
Metode HTTP / GET●  Folosit pentru a obtine starea unei resurse●  Cererea poate contine headere dar nu   body●  Cereri rep...
Metode HTTP / HEAD●  Exact ca si GET, returneaza doar headerele   fara body●  Folosit la verifica existenta unei resurse s...
Metode HTTP / PUT●  Folosit pentru insert si update-uri●  Mesajul trebuie sa contina o   reprezentare a resursei pe care c...
Metode HTTP / POST●  Folosit pentru a crea o resursa noua intr-o   colectie●  Folosit pentru a invoca controleri●  Permis ...
Metode HTTP / DELETE●  Folosita pentru a sterge o resursa dintr-o   colectie●  O data stearsa cu DELETE resursa nu   mai t...
Metode HTTP / OPTIONS●  Folosita pentru a sterge o obtine lista de   operatii posibile asupra unei resurse●  Allow: GET, P...
Versionarea serviciilor●  Mai multe abordari   o  Versiune in path       •  http://example.com/timetrack/v1/companies/yond...
Paginare●  Ascundeti complexitate in spate la ?   o  https://api.taskmgm.com/v1/companies?limit=10&offset=0●  Puteti folos...
CautareFie prin controller  https://api.taskmgm.com/v1/companies/searchAscundeti complexitate in spate la ?   https://api....
Coduri de răspuns, tratarea exceptiilorHttp status code : 401 Unauthorized●  {   o  “developerMessage” : “Verbose, plain l...
Coduri de răspuns, tratarea exceptiilor                     Totul aSuccess            funcționatErroare            Aplicat...
Coduri de răspuns, tratarea exceptiilor●  HTTP Defineste 5 categorii 1XX     Informational      Comunica informatii la niv...
Coduri de răspuns, tratarea exceptiilorSuccess              200 OKErroare             400 Bad client              ReuestEr...
Coduri de răspuns, tratarea exceptiilor                                          41
Coduri de răspuns, tratarea exceptiilor  Creare        201 Created Resursa          404 Not gresita           Found  Lipsa...
Coduri de răspuns, tratarea exceptiilor●  200 (“OK”)   o    Codul pe care clientii spra sa-l vada   o    Indica success   ...
Coduri de răspuns, tratarea exceptiilor●  204 (“No Content”)   o  Operatia e reusita dar nu exista continut de returnat (D...
Coduri de răspuns, tratarea exceptiilor●  400 (“Bad Request”)   o  Mesaj de erroare generic cind nici un alt 4xx nu este p...
Coduri de răspuns, tratarea exceptiilor●  406 (“Not Acceptable”)   o  Formatul cerut de client nu este suportat (Ex. clien...
ResurseWeb API Design?Crafting Interfaces that DevelopersLoveBy Brian MulloyEbook gratuit oferit de apigeehttp://apigee.co...
ResurseREST API Design RulebookDesigning Consistent RESTfulWeb Service InterfacesBy Mark MassePublisher: OReilly MediaRele...
Resurse1. Atlassian REST API Design Guidelines version 1https://developer.atlassian.com/display/DOCS/Atlassian+REST+API+De...
Întrebări?      photo cc by http://www.flickr.com/photos/horiavarlan/4273168957/                                          ...
Thank You !Please fill the evaluation form slide       photo cc by http://www.flickr.com/photos/wwworks/4759535950/       ...
Designing RESTful webservices and web apis
Upcoming SlideShare
Loading in...5
×

Designing RESTful webservices and web apis

679

Published on

Whether you're building your single page application, your mobile application or just want to open up your platform to innovation one thing that you will need is well designed API and services. Learn what are the best practices and approaches in designing your REST based web services and APIs in order to create your own rock solid platforms.

Presentation in Romanian at CodeCamp Iasi April, 2013

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
679
On Slideshare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
6
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Designing RESTful webservices and web apis

  1. 1. Designing RESTfull WebServices and Web APIs Best Practices Occasion: CodeCamp Iasi Date: 20-04-2013 Present: Remus Pereni / Software Architect / remus.pereni@tss-yonder.comClassification: Public
  2. 2. Remus PereniSoftware Architect Yonder RomaniaTSS-Yonder http://tss-yonder.com @tssyonderWeb & Mobile Web & Java Cluj Napoca Calea Dorobantilor 18-20 PowerTwitter: @remuspereni Business CenterWeb: http://remus.pereni.org Iasi Sos. Pacurari 138 3
  3. 3. Evoluție  API-­‐uri   De ce avem Bineinteles avem De ce avem Bineinteles canevoie de Web website! nevoie de API? avem un API! site?1995 2000 2005 2013 4  
  4. 4. Evoluție  API-­‐uri  From Open APIs: State of the Market by John Musser, ProgrammableWeb 5  
  5. 5. Evoluțe  API-­‐uri  From Open APIs: State of the Market by John Musser, ProgrammableWeb 6  
  6. 6. REST  vs.  SOAP:  Simplicity  wins  again  From Open APIs: State of the Market by John Musser, ProgrammableWeb Based on directory of 3,200 web APIs listed at ProgrammableWeb, May 2011 7  
  7. 7. Componente 8
  8. 8. Resurse Web●  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/getLog 9
  9. 9. Resurse Web/{colecții} /{store-uri}conțin-> /{documente} care stocheză-> care au datele propriuzise 10
  10. 10. Resurse Web/companies /1234- colectie- lista de companii - document - detalii companie 1234 11
  11. 11. Resurse Web●  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/12182 12
  12. 12. Resurse Web/projects /favorites- colectie /1234- lista de -un storeproiecte -returneaza tot - document o listă - detalii proiect -cu proiectele favorit favorite 13
  13. 13. Resurse Web●  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/1234 14
  14. 14. Resurse Web/{colecții} /{store-uri}conțin-> /{documente} care stocheză-> /{controlere} care au datele modeleaza propriuzise un concept procedural 15
  15. 15. Resurse Web/users /1234- colectie /resetPassword- lista de - documentutilizatori - detalii unui -controler anumit user reseteaza parola 16
  16. 16. Resurse Web●  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/login 17
  17. 17. Operații asupra resurselor / Metode HTTPResursă POST GET PUT DELETE Crează Citește Actualizează Sterge/companies 201 Created 200 OK 405 Method 405 Method Crează o nouă Obtine lista de Not Allowed Not Allowed companie companii sau 200 OK sau 200 OK Actualizeaza Nimic sau toată lista de Sterge toata companii lista de companii/companies/ 405 Method 200 OK 200 OK 200 OK1234 Not Allowed Obtine detalii Daca exista Sterge sau despre compania compania 404 Not compania 1234 1234 Found 1234 actualizeaza sau 404 Not altfel erroare: Found daca 404 Not nu există Found 18
  18. 18. URI, definiție●  RFC 3986●  Syntaxa unui URI e: o  scheme o  "://" o  authority o  "/" path o  [ "?" query ] o  [ "#" fragment ]●  http://example.com/v1/users#name? q=Remus 19
  19. 19. URI / Best practice-uri●  Folositi substantive la plural si nu verbe o  /companies o  /users o  /getUsers o  /getCompanies●  Nu amestecati plural si singular, nu e consistent o  /companies o  /user o  /users 20
  20. 20. URI / Best practice-uriUtilizati charactere mici in URI-uri (lowercase)●  https://api.taskmgm.com/v1/users o  o resursa●  HTTP://Api.Taskmgm.com/v1/users o  aceiasi resursa ca mai sus●  https://api.taskmgm.com/v1/Users o  o alta resursaDe ce?RFC 3896 defineste URI-urile case sensitive exceptind Protocol-ul sicomponentele host-uluischeme "://" authority "/" path [ "?" query ] [ "#" fragment ] 21
  21. 21. URI / Best practice-uriNu includeti extensie de fisiere in URI-uri●  https://api.taskmgm.com/v1/users/1234.jsonMecanismele HTTP pentru negocierea continutuluiHeaderele o  ACCEPT o  ContentType 22
  22. 22. Formate multiple●  Implicit parte din HTTP●  header-ul: Accept  Accept                  =  "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=json   23
  23. 23. URI / Best practice-uri●  Forward slash separator (/) indica relatii hierarhice o http://example.org/vinzari/2012/08/01 24
  24. 24. URI / Best practice-uri●  Trailing forward slash (/) nu trebuie sa termine un URI o  http://example.org/companies/1234/ o  http://example.org/companies/1234●  De ce? o  Nu adauga valoare semantica o  Poate cauza confuzie (2 uri-uri diferite trebuie sa identifice 2 resurse diferite) 25
  25. 25. URI / Best practice-uriHypens (-) pot fi folosite pentru a imbunatatiireadability-ul URI-urilor http://example.org/blogs/remus-pereni/entry/primul-post 26
  26. 26. URI / Best practice-uriUnderscore (_) nu ar trebui folosite Link-urile de obicei sunt afisate cu underline si atuncea underscore poate fi confundat 27
  27. 27. Metode HTTP / GET●  Folosit pentru a obtine starea unei resurse●  Cererea poate contine headere dar nu body●  Cereri repetate la GET nu e voie sa aiba efecte secundare / duca la modificari de stare●  Cache-urile depind de abilitatea de a servi un raspuns fara a mai contacta serverul original 28
  28. 28. Metode HTTP / HEAD●  Exact ca si GET, returneaza doar headerele fara body●  Folosit la verifica existenta unei resurse sau a metadatelor legat de ea 29
  29. 29. Metode HTTP / PUT●  Folosit pentru insert si update-uri●  Mesajul trebuie sa contina o reprezentare a resursei pe care clientul doreste sa o stocheze pe server●  Continutul mesajului poate sa nu fie identic cu cea ce ar primi de la un request GET. Poate contine doar valorile mutabile / variabile din starea resursei●  Operatiune Idempotenta 30
  30. 30. Metode HTTP / POST●  Folosit pentru a crea o resursa noua intr-o colectie●  Folosit pentru a invoca controleri●  Permis pentru orice actiune fara legatura cu repetabilitatea sau efectele colaterale (unsafe & non-idempotent)●  Nu este garantata repetabilitatea●  A nu se folosi pentru a obtine / sterge / actualiza resurse 31
  31. 31. Metode HTTP / DELETE●  Folosita pentru a sterge o resursa dintr-o colectie●  O data stearsa cu DELETE resursa nu mai trebuie sa apartina colectiei (orice GET sau HEAD pe resursa respectiva trebuie sa se termine cu 404 NOT FOUND 32
  32. 32. Metode HTTP / OPTIONS●  Folosita pentru a sterge o obtine lista de operatii posibile asupra unei resurse●  Allow: GET, PUT, DELETE 33
  33. 33. Versionarea serviciilor●  Mai multe abordari o  Versiune in path •  http://example.com/timetrack/v1/companies/yonder o  Versiune in header●  Versiune in header / parte din negocieri o  Un URI trebuie sa identifice constant o resursa o  Modificarea URI-ului presupune o resursa noua o  Deci V1 & V2 denota 2 resurse diferite -> Incorect 34
  34. 34. Paginare●  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 ele 35
  35. 35. CautareFie prin controller https://api.taskmgm.com/v1/companies/searchAscundeti complexitate in spate la ? https://api.taskmgm.com/v1/companies?search=Yonder 36
  36. 36. Coduri de răspuns, tratarea exceptiilorHttp status code : 401 Unauthorized●  { o  “developerMessage” : “Verbose, plain language description of the problem for the app developer with hints about how to fix it.” o  , “userMessage”:”Pass this message on to the app user if needed.” o  , “errorCode” : 12345 o  , “more info”: http://dev.teachdogrest.com/errors/12345●  } 37
  37. 37. Coduri de răspuns, tratarea exceptiilor Totul aSuccess funcționatErroare Aplicatia a facut ceva client greșitErroare Ups s-a intinplatserver ceva aiurea 38
  38. 38. Coduri de răspuns, tratarea exceptiilor●  HTTP Defineste 5 categorii 1XX Informational Comunica informatii la nivel de protocol 2XX Success Cererea clientului acceptata cu success 3XX Redirectari Indica ca sunt nevoie actiuni suplimentare pentru a complecta requestul 4XX Errori client Erroare datorata in general request-ului / Clientului 5XX Errori server Erroare datorata in general serverului 39
  39. 39. Coduri de răspuns, tratarea exceptiilorSuccess 200 OKErroare 400 Bad client ReuestErroare 500 Internalserver Server Error 40
  40. 40. Coduri de răspuns, tratarea exceptiilor 41
  41. 41. Coduri de răspuns, tratarea exceptiilor Creare 201 Created Resursa 404 Not gresita Found Lipsa 401autorizații Unauthorized Metoda 403 ne- Forbidden permisa 42
  42. 42. Coduri de răspuns, tratarea exceptiilor●  200 (“OK”) o  Codul pe care clientii spra sa-l vada o  Indica success o  In general trebuie sa includa un raspuns in body o  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 noua bazat pe cererea clientului o  Poate fi si raspuns al apelului unui controller in cazul in care o resursa este creata●  202 (“Accepted”) o  Folosit pentru raspunsuri asincrone o  O operatiune lunga a fost inceputa, pare valida dar poate inca genera errori o  In general folosit la controlere 43
  43. 43. Coduri de răspuns, tratarea exceptiilor●  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 ea o  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 raspuns potential nedorit poate trimite in Location un URI la o resursa care poate prezenta interes pentru clienti●  304 (“Not Modified”) o  Similar cu 204 (“No Content) in sensul ca body-ul e gol o  Clientul are deja cea mai recenta versiune o  Folosit impreuna cu alte headere ce determina HTTP Conditionale 44
  44. 44. Coduri de răspuns, tratarea exceptiilor●  400 (“Bad Request”) o  Mesaj de erroare generic cind nici un alt 4xx nu este potrivit o  Raspunsul poate contine body cu mesaj detaliat legat de erroare●  401 (“Unauthorized”) o  Nu are authorizarea necesara sau nu a asigurat nici un fel de authorizare●  403 (“Forbidden”) o  Indica ca request-ul e corect dar backend-ul refuza sa-l onoreze o  Nu este o problema de autorizare (ar fi 401), poate clientul nu are 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 o resursa read only) o  Trebuie sa se trimita inapoi header-ul Allow: GET, POST cu metodele suportate 45
  45. 45. Coduri de răspuns, tratarea exceptiilor●  406 (“Not Acceptable”) o  Formatul cerut de client nu este suportat (Ex. clientul cere application/xml prin intermediul headerului Accept dar serverul are pregatit doar application/json●  409 (“Conflict”) o  Daca se incearca punerea unei resurse intr-o stare inconsistenta o  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 de header-ul Content-Type o  Ex. Body-ul contine application/xml dar serverul stie sa trateze doar application/json●  500 (“Internal Server Error”) o  Probleme pe partea de server, ex exceptii aruncate si ne tratate 46
  46. 46. ResurseWeb API Design?Crafting Interfaces that DevelopersLoveBy Brian MulloyEbook gratuit oferit de apigeehttp://apigee.com/about/content/web-api-design 47
  47. 47. ResurseREST API Design RulebookDesigning Consistent RESTfulWeb Service InterfacesBy Mark MassePublisher: OReilly MediaReleased: October 2011Pages: 116 48
  48. 48. Resurse1. 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/ 49
  49. 49. Întrebări? photo cc by http://www.flickr.com/photos/horiavarlan/4273168957/ 50
  50. 50. Thank You !Please fill the evaluation form slide photo cc by http://www.flickr.com/photos/wwworks/4759535950/ 51
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×