budowa poprawnego i intuicyjnego api rest hateoas devfest@2013
DESCRIPTION
Prezentacja z devfest 2013 http://www.devfest.pl v.1.0 Allegro.plTRANSCRIPT
![Page 2: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/2.jpg)
{ Agenda, czyli o tym, co będzie !API REST HATEOAS Różne podejście w API Github, Facebook, Twitter i Linkedin Uwagi
![Page 3: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/3.jpg)
API
application programming interface
![Page 4: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/4.jpg)
API
punkt wejścia usługi
![Page 5: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/5.jpg)
API
PO co nam API?
dostępność
skalowalność
zasięg
![Page 6: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/6.jpg)
API
Dla KOGO?
biznes
deweloper
klient
![Page 7: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/7.jpg)
API
A gdy nie ma API..
powstają nieskalowalne, drogie w utrzymaniu monolity
ograniczamy liczbę klientów (rynek mobilny, tv, ..)
![Page 8: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/8.jpg)
API
Hackathon, czyli „sprzedajemy” nasze API (jako startup)
http://www.hackathon.io/https://www.hackerleague.org/hackathons
![Page 9: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/9.jpg)
API
Bezpieczeństwo jest najważniejsze
cały ruch po HTTPS
używaj OAUTH 2.0
separuj dane wejściowe od autoryzacji (w nagłówku)
nie wymyślaj autoryzacji na nowo..
![Page 10: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/10.jpg)
OAuth 2.0 vs 1.0
wsparcie dla autoryzacji poza przeglądarką
nie wymaga szyfrowania kluczy tylko połączenia https
czas życia tokena mógł być wieczny
pojęcie odnawiania tokena (bez akcji użytkownika)
![Page 11: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/11.jpg)
OAuth 2.0
Autoryzacja
![Page 12: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/12.jpg)
Autoryzacja
OAuth 2.0
Basic Authentication
Personal Access Tokens
![Page 13: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/13.jpg)
Autoryzacja
OAuth 2.0
appsecret_proof (dodatkowo zabezpiecza token)
szczegółowa konfiguracja ustawień aplikacjitokeny z krótkim i długim czasem życia
![Page 14: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/14.jpg)
Autoryzacja
OAuth 2.0
Application-only authentication (kontekst aplikacji)
![Page 15: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/15.jpg)
REST jest wzorcem architektury
REST
representational state transfer
![Page 16: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/16.jpg)
REST jest wzorcem architektury
REST
reprezentacja zasobów usługi
![Page 17: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/17.jpg)
REST
zasoby
jednorodny interfejs
bez stanu
reprezentacja
![Page 18: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/18.jpg)
REST, reprezentacja
JSON (ECMA-404)
{ { "id": "7", "category": { "id": "4", "name": "Lions" } }
![Page 19: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/19.jpg)
REST, reprezentacja
XML
{<response> <id>7</id> <category> <id>4</id> <name>Lions</name> </category> </response>
![Page 20: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/20.jpg)
REST, reprezentacja
Poproszę te dane jako..
/posts/1?format=json
/posts/1.xml
Accept: application/json
![Page 21: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/21.jpg)
REST, reprezentacja
Ale dlaczego to tyle waży?
klient: Accept-Encoding: gzip, deflate
serwer: Content-Encoding: gzip
![Page 22: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/22.jpg)
REST, zasoby
Czym jest zasób?
/posts
/posts, /news - rzeczownik w liczbie mnogiej
/posts/:id
zasób powinien mieć maksymalnie 2 bazowe adresy url
konkretne nazwy dla zasobów (unikaj abstrakcji)
![Page 23: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/23.jpg)
REST, zasoby
Akcje na zasobachGET - pobierz, szukaj (http status 200 OK)
POST - utwórz (http status 201 CREATED z location)
PUT - aktualizuj (http status 200 OK)
PATCH - częściowa aktualizacja (http status 200 OK)
DELETE - usuń (http status 204 NO CONTENT)
![Page 24: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/24.jpg)
REST, zasoby
Niestandardowe akcje na zasobachNie mieszaj akcji na zasobach w adresie do zasobu
POST /posts/:id/rate ?? Czy ocena jest akcją?
POST /rates?post=:id ?? Czy ocena jest zasobem?
.. chyba, że ma to sens
![Page 25: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/25.jpg)
REST, zasoby
A jeśli zasoby są zależne od siebie?Pokaż mi posty użytkownika o id..
GET /users/:id/posts
oraz takie, które dodał wczoraj
GET /users/:id/posts?createdTime=08.11.2013
![Page 26: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/26.jpg)
REST, zasoby
Znajdź niepoprawne adresy zasobów/post/show/:id
/posts/show/:id (początkowo w Ruby)
/users/1/posts/rated/5
/users/1/pay/100.00/to/2
![Page 27: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/27.jpg)
REST, zasoby
Potrzebuję ten zasób w wersji..Należy bezwzględnie wymagać określenia wersji
nagłówek: Accept: application/vnd.github.beta+json
parametr w url: /v1/posts
parametr w query string: /posts?v=1.0
wersja jako kolejne liczby całkowite
![Page 28: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/28.jpg)
REST, zasoby
Partial response, czyli potrzebuję tylko..
Definicja podzbioru pól w odpowiedzi z API
parametr fields=field1,field2
:(field1,field2,field3...)
![Page 29: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/29.jpg)
REST, cache
Często pytam o to samo..Przechowujemy tylko odpowiedź z metod GET
varnish po stronie serwera
przez nagłówki expires, cache-control, etag po stronie klienta
![Page 30: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/30.jpg)
REST, obsługa błędów
Jakie informacje powinno zwrócić API ?
opis błędu dla dewelopera aplikacji
opis błędu dla użytkownika aplikacji
wewnętrzny kod błędu API
informacja o statusie http
![Page 31: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/31.jpg)
REST, obsługa błędów
Czy status 200 dla błędów może się przydać ?
suppress_response_codes=truezwracało status 200 dla błędów
Tak, aplikacje flash i javascript
![Page 32: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/32.jpg)
REST, obsługa błędów
Statusy http błędów wywołania API
4xx - błędy po stronie klienta API
5xx - błędy po stronie serwera API
![Page 33: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/33.jpg)
400 Bad Request
REST, obsługa błędów
401 Unauthorized (np. problem z autoryzacją OAuth)
403 Forbidden (uprawnienia lub przekroczony limit)
404 Not Found
406 Not Acceptable
![Page 34: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/34.jpg)
410 Gone (podana wersja api nie jest wspierana)
REST, obsługa błędów
420 Method Failure (limit wywołań dla wyszukiwania)
429 Too Many Requests (j.w)
502 Bad Gateway (przerwa techniczna lub awaria)
503 Service Unavailable (usługa jest przeciążona)504 Gateway timeout (problemy z obsługą żądania)
![Page 35: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/35.jpg)
400 Bad Request
REST, obsługa błędów
401 Unauthorized (np. problem z autoryzacją OAuth)
403 Forbidden (uprawnienia lub przekroczony limit)
404 Not Found
405 Method Not Allowed (GET zamiast POST,..)
![Page 36: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/36.jpg)
400 Bad Request
REST, obsługa błędów
![Page 37: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/37.jpg)
400 Bad Request
REST, obsługa błędów
422 Unprocessable Entity (problem z weryfikacją)
![Page 38: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/38.jpg)
X-Rate-Limit-Limit (limit dla danego zapytania)
REST, limity
X-Rate-Limit-Remaining (dostępna pula, 15 min okno)
X-Rate-Limit-Reset (czas odnowienia limitu)
![Page 39: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/39.jpg)
X-RateLimit-Limit (limit dla danego zapytania)
X-RateLimit-Remaining (dostępna pula)
X-RateLimit-Reset (czas odnowienia limitu)
GET /rate_limit
REST, limity
![Page 40: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/40.jpg)
https://www.linkedin.com/secure/developer?showthrottles=&app_id=appId&app_name=appName
REST, limity
status 403 z informacją o „throttle limit”
![Page 41: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/41.jpg)
Error, Code: 17, User request limit reached
REST, limity
Error, Code: 4, Application request limit reached
![Page 42: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/42.jpg)
HATEOAS
HYPERMEDIA AS THE ENGINE OF APPLICATION STATE
relacje między zasobami w postaci odnośników
lista dostępnych metod API
nagłówki content-type i accept
![Page 43: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/43.jpg)
HATEOAS
Tekst
http://blog.perfectapi.com/2012/opinionated-rpc-apis-vs-restful-apis/
![Page 44: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/44.jpg)
Dokumentacja
Jeśli API jest intuicyjne to po co dokumentacja ?
http://swagger.wordnik.com/
![Page 45: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/45.jpg)
Dokumentacja
Jak dobrze że mogę przetestować API
https://dev.twitter.com/console
https://developers.facebook.com/tools/explorer
![Page 46: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/46.jpg)
Access-Control-Allow
Dostęp do API z innej „domeny”
Access-Control-Allow-Methods: GET, POST, DELETE, PUT
Access-Control-Allow-Origin: * (github pozwala ustawić domenę)
Access-Control-Allow-Headers: Content-Type, Authorization, access_token
![Page 47: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/47.jpg)
SDK
Dostarcza obiekty zapytań i odpowiedzi
Pozwala ukryć błędy projektowe API
Dostarcza interfejs API
Wsparcie dla obsługi błędów
Jak mogę Ci pomóc w integracji?
![Page 48: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/48.jpg)
SDK
https://developer.linkedin.com/documents/libraries-and-tools
oficjalne SDK tylko dla javascript
wsparcie w różnych framework’ach (community)
![Page 49: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/49.jpg)
SDK
http://developer.github.com/v3/libraries
oficjalne SDK (octokit) dla c#, ruby i obj-c
![Page 50: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/50.jpg)
SDK
oficjalne SDK dla iOS, Android, web (javascript, php)
olbrzymie wsparcie w projektach community
![Page 51: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/51.jpg)
SDK
https://dev.twitter.com/docs/twitter-libraries
oficjalne SDK hbc dla java (nie jest klientem REST)
olbrzymie wsparcie w projektach community
![Page 52: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/52.jpg)
Uwagi
Światowy standard formatowanie daty i czasu
Unikaj magicznych wartości (price = -1)
Pola id zwracaj jako typu znakowego (string)
Proste rzeczy w przedstawiaj w prosty sposób
![Page 53: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/53.jpg)
Przyjęta notacja dla nazwa parametrów (cammel case)
Znikające pola w odpowiedzi
Definiowanie akcji na zasobach (czasowniki)
Uwagi
Stronicowanie wyników (limit i offset zamiast page)
![Page 54: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/54.jpg)
Przyjmowanie rozbudowanych danych wejściowych w metodzie GET
Uwagi
Unikaj domyślnych wartości dla parametrów
![Page 55: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/55.jpg)
Zagadka
Czy można wysłać metodą GET dane w body?
![Page 56: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/56.jpg)
{Ciekawy temat, chcę więcej! !http://blog.steveklabnik.com/posts/2011-08-07-some-people-understand-rest-and-http http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http http://www.informit.com/articles/article.aspx?p=1566460 http://blog.perfectapi.com/2012/opinionated-rpc-apis-vs-restful-apis/ !http://info.apigee.com/Portals/62317/docs/web%20api.pdf
![Page 57: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/57.jpg)
Pytania ?
![Page 58: Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013](https://reader033.vdocuments.mx/reader033/viewer/2022052905/5584d228d8b42af1138b5265/html5/thumbnails/58.jpg)
Dziękuję za uwagę