• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Iasi code camp 20 april 2013 designing res tfull webservices and web apis - remus pereni
 

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

on

  • 291 views

 

Statistics

Views

Total Views
291
Views on SlideShare
291
Embed Views
0

Actions

Likes
0
Downloads
5
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • 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 Iasi code camp 20 april 2013 designing res tfull webservices and web apis - remus pereni Presentation Transcript

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