Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.
!

Budowa RESTowego api w oparciu o HATEOAS

v1.1 braincode@2014

mateusz.stepniak@allegro.pl
{

Agenda, czyli o tym, co będzie
!
API (WEBAPI)
REST
HATEOAS
Różnice w API Github, Facebook, Twitter i Linkedin
Uwagi
Pyt...
API

application

programming

interface
API

punkt

wejścia

usługi
API

Po co nam API?
dostępność
skalowalność
zasięg
API

Dla KOGO?
biznes
deweloper
klient
API

A gdy nie ma API..
powstają nieskalowalne, drogie w utrzymaniu monolity

ograniczamy liczbę klientów (mobilni, tv, ag...
API

Hackathon, czyli „sprzedajemy”
nasze API (jako startup)
http://www.hackathon.io/
https://www.hackerleague.org/hackath...
API

Bezpieczeństwo jest najważniejsze
problem root (android) i jailbreak (iOS)
cały ruch po HTTPS
użycie OAUTH 2.0
separa...
OAuth 2.0 vs 1.0

wsparcie dla autoryzacji poza przeglądarką
nie wymaga szyfrowania kluczy tylko połączenia https
czas życ...
Autoryzacja

OAuth 2.0
Autoryzacja

OAuth 2.0
Basic Authentication
curl -u „login:pass" https://api.github.com/repos/user/repo

Personal Access T...
Autoryzacja

OAuth 2.0
appsecret_proof (dodatkowo zabezpiecza token)
https://developers.facebook.com/docs/graph-api/securi...
Autoryzacja

OAuth 2.0
Application-only authentication (kontekst aplikacji)
https://dev.twitter.com/docs/auth/application-...
REST jest wzorcem architektury
REST

representational

state

transfer
REST jest wzorcem architektury
REST

reprezentacja

zasobów

usługi
REST
reprezentacja
zasoby
jednorodny interfejs
bez stanu
REST, reprezentacja

JSON (ECMA-404)

{

{
"id": "7",
"category": {
"id": "4",
"name": "Lions"
}
}
REST, reprezentacja

XML

{

<response>
<id>7</id>
<category>
<id>4</id>
<name>Lions</name>
</category>
</response>
REST, reprezentacja

Poproszę te dane jako..
/posts/1?format=json
/posts/1.xml
Accept: application/json
Accept: applicatio...
REST, reprezentacja

Ale dlaczego to tyle waży?
klient:

Accept-Encoding: gzip, deflate

serwer: Content-Encoding: gzip
REST, zasoby

Czym jest zasób?
/posts, /news - rzeczownik w liczbie mnogiej
zasób powinien mieć maksymalnie 2 bazowe adres...
REST, zasoby

Przykłady
/events
/repos/:owner/:repo/events
/feeds
/statuses

/notifications
REST, zasoby

Akcje na zasobach
GET - pobierz, szukaj (http status 200 OK)
POST - utwórz (http status 201 CREATED z locati...
REST, zasoby

Niestandardowe akcje na zasobach
Nie mieszaj akcji na zasobach w adresie do zasobu
POST /posts/:id/rate ?? C...
REST, zasoby

A jeśli zasoby są zależne od siebie?
Pokaż mi posty użytkownika o id..
GET /users/:id/posts
Pokaż mi posty u...
REST, zasoby

Znajdź niepoprawne adresy zasobów
/post/show/:id
/posts/show/:id (początkowo w Ruby)
/users/1/posts/rated/5
...
REST, zasoby

Potrzebuję ten zasób w wersji..
Należy bezwzględnie wymagać określenia wersji
wersja jako kolejne liczby cał...
REST, zasoby

Partial response, czyli potrzebuję tylko..
Definicja podzbioru pól w odpowiedzi z API

parametr fields=field1,fi...
REST, cache

Często pytam o to samo..
Cache’ujemy tylko odpowiedzi z metod GET

varnish po stronie serwera
przez nagłówki ...
REST, obsługa błędów

Jakie informacje powinno zwrócić API ?
opis błędu dla dewelopera aplikacji
opis błędu dla użytkownik...
REST, obsługa błędów

Czy status 200 dla błędów może się przydać ?
Tak, aplikacje flash
suppress_response_codes=true
kiedyś...
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 ...
REST, obsługa błędów

400 Bad Request
401 Unauthorized (np. problem z autoryzacją OAuth)
403 Forbidden (uprawnienia lub pr...
REST, obsługa błędów

410 Gone (podana wersja api nie jest wspierana)
420 Method Failure (limit wywołań dla wyszukiwania)
...
REST, obsługa błędów

400 Bad Request
401 Unauthorized (np. problem z autoryzacją OAuth)
403 Forbidden (uprawnienia lub pr...
REST, obsługa błędów

400 Bad Request
404 Not Found
REST, obsługa błędów

400 Bad Request
404 Not Found
422 Unprocessable Entity (problem z weryfikacją)
REST, limity

X-Rate-Limit-Limit (limit dla danego zapytania)
X-Rate-Limit-Remaining (dostępna pula, 15 min okno)
X-Rate-L...
REST, limity

X-RateLimit-Limit (limit dla danego zapytania)
X-RateLimit-Remaining (dostępna pula)
X-RateLimit-Reset (czas...
REST, limity

https://www.linkedin.com/secure/developer?
showthrottles=&app_id=appId&app_name=appName
status 403 z informa...
REST, limity

Error, Code: 17, User request limit reached
Error, Code: 4, Application request limit reached
HATEOAS

HYPERMEDIA AS THE ENGINE OF
APPLICATION STATE
relacje między zasobami w postaci odnośników
lista dostępnych metod...
HATEOAS

Przykład (reponse body)

{

curl https://api.github.com

{
"current_user_url": „https://api.github.com/user",
"em...
HATEOAS

Przykład (nagłówki)

{

curl https://api.github.com/users?access_token=token

Link: <https://api.github.com/users...
HATEOAS

http://blog.perfectapi.com/2012/opinionated-rpc-apis-vs-restful-apis/
Dokumentacja

Potrzebna nam jeszcze
dokumentacja ?
http://swagger.wordnik.com/
Dokumentacja

Jak dobrze, że mogę przetestować API
https://dev.twitter.com/console
https://developers.facebook.com/tools/e...
Dokumentacja

49
Dokumentacja

50
Dokumentacja

Dostęp do API z innej „domeny”
Access-Control-Allow-Origin: * (github pozwala ustawić domenę)
Access-Control...
SDK

Jak mogę wam pomóc w integracji?
Pozwala ukryć błędy projektowe API
Dostarcza obiekty zapytań i odpowiedzi
Dostarcza ...
SDK

https://developer.linkedin.com/documents/libraries-and-tools

oficjalne SDK tylko dla javascript
wsparcie w różnych fr...
SDK

http://developer.github.com/v3/libraries
oficjalne SDK (octokit) dla c#, ruby, go i obj-c
SDK

oficjalne SDK dla iOS, Android, javascript, php, unity
olbrzymie wsparcie w projektach community
SDK

https://dev.twitter.com/docs/twitter-libraries
oficjalne SDK hbc dla java (streaming api, not REST)
olbrzymie wsparcie...
Uwagi

Pola id zwracaj jako typu znakowego
"id": 187462027801919500,

"id_str": "187462027801919489"

Światowy standard fo...
Uwagi

Definiowanie akcji na zasobach
czasowniki dla akcji lub nowy zasób (rzeczownik)

Przyjęta notacja dla nazwa parametr...
Uwagi

Nie pozwalaj na znikające pola w odpowiedzi
Przyjmowanie rozbudowanych danych wejściowych
w metodzie GET
Zagadka
Czy można wysłać metodą GET dane w body?
curl -X GET --data '{"id": "2223"}' http://echo.200please.com -H "Content...
{

Ciekawy temat, chcę więcej!
!
!
http://blog.steveklabnik.com/posts/2011-08-07-some-peopleunderstand-rest-and-http
http:...
Warsztaty

https://github.com/Zenedith/swagger-jersey2-gradle-demo-app

gradle
swagger
jersey2
jetty
Pytania ?
Dziękuję za uwagę
Prochain SlideShare
Chargement dans…5
×

Budowa RESTowego api w oparciu o HATEOAS

4 129 vues

Publié le

Budowa RESTowego api w oparciu o HATEOAS
@braincodemobi2014
EN: https://blog.allegrogroup.com/it/braincode-mobi1-mobile-people-move-your-brains
PL: https://blog.allegrogroup.com/it/braincode-mobi1-mobilni-ruszcie-mozgi
http://info.put.poznan.pl/2013/12/16/2004
v1.1
Allegro.pl

Publié dans : Technologie
  • Soyez le premier à commenter

Budowa RESTowego api w oparciu o HATEOAS

  1. 1. ! Budowa RESTowego api w oparciu o HATEOAS v1.1 braincode@2014 mateusz.stepniak@allegro.pl
  2. 2. { Agenda, czyli o tym, co będzie ! API (WEBAPI) REST HATEOAS Różnice w API Github, Facebook, Twitter i Linkedin Uwagi Pytania
  3. 3. API application programming interface
  4. 4. API punkt wejścia usługi
  5. 5. API Po co nam API? dostępność skalowalność zasięg
  6. 6. API Dla KOGO? biznes deweloper klient
  7. 7. API A gdy nie ma API.. powstają nieskalowalne, drogie w utrzymaniu monolity ograniczamy liczbę klientów (mobilni, tv, agd, ..)
  8. 8. API Hackathon, czyli „sprzedajemy” nasze API (jako startup) http://www.hackathon.io/ https://www.hackerleague.org/hackathons
  9. 9. API Bezpieczeństwo jest najważniejsze problem root (android) i jailbreak (iOS) cały ruch po HTTPS użycie OAUTH 2.0 separacja danych od autoryzacji (w nagłówku) nie wymyślajmy autoryzacji na nowo..
  10. 10. 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)
  11. 11. Autoryzacja OAuth 2.0
  12. 12. Autoryzacja OAuth 2.0 Basic Authentication curl -u „login:pass" https://api.github.com/repos/user/repo Personal Access Tokens curl https://api.github.com/user?access_token=cb4sssdsdsdsd
  13. 13. Autoryzacja OAuth 2.0 appsecret_proof (dodatkowo zabezpiecza token) https://developers.facebook.com/docs/graph-api/securing-requests/ tokeny z krótkim i długim czasem życia
  14. 14. Autoryzacja OAuth 2.0 Application-only authentication (kontekst aplikacji) https://dev.twitter.com/docs/auth/application-only-auth
  15. 15. REST jest wzorcem architektury REST representational state transfer
  16. 16. REST jest wzorcem architektury REST reprezentacja zasobów usługi
  17. 17. REST reprezentacja zasoby jednorodny interfejs bez stanu
  18. 18. REST, reprezentacja JSON (ECMA-404) { { "id": "7", "category": { "id": "4", "name": "Lions" } }
  19. 19. REST, reprezentacja XML { <response> <id>7</id> <category> <id>4</id> <name>Lions</name> </category> </response>
  20. 20. REST, reprezentacja Poproszę te dane jako.. /posts/1?format=json /posts/1.xml Accept: application/json Accept: application/vnd.github.beta+json
  21. 21. REST, reprezentacja Ale dlaczego to tyle waży? klient: Accept-Encoding: gzip, deflate serwer: Content-Encoding: gzip
  22. 22. REST, zasoby Czym jest zasób? /posts, /news - rzeczownik w liczbie mnogiej zasób powinien mieć maksymalnie 2 bazowe adresy url /posts /posts/:id konkretne nazwy dla zasobów (unikajmy abstrakcji)
  23. 23. REST, zasoby Przykłady /events /repos/:owner/:repo/events /feeds /statuses /notifications
  24. 24. REST, zasoby Akcje na zasobach GET - 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)
  25. 25. REST, zasoby Niestandardowe akcje na zasobach Nie 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
  26. 26. REST, zasoby A jeśli zasoby są zależne od siebie? Pokaż mi posty użytkownika o id.. GET /users/:id/posts Pokaż mi posty użytkownika, które dodał wczoraj GET /users/:id/posts?createdTime=16.01.2014
  27. 27. 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
  28. 28. REST, zasoby Potrzebuję ten zasób w wersji.. Należy bezwzględnie wymagać określenia wersji wersja jako kolejne liczby całkowite nagłówek: Accept: application/vnd.github.beta+json parametr w url: /v1/posts parametr w query string: /posts?v=1.0
  29. 29. REST, zasoby Partial response, czyli potrzebuję tylko.. Definicja podzbioru pól w odpowiedzi z API parametr fields=field1,field2 :(field1,field2,field3...)
  30. 30. REST, cache Często pytam o to samo.. Cache’ujemy tylko odpowiedzi z metod GET varnish po stronie serwera przez nagłówki expires, cache-control, etag po stronie klienta
  31. 31. 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
  32. 32. REST, obsługa błędów Czy status 200 dla błędów może się przydać ? Tak, aplikacje flash suppress_response_codes=true kiedyś zwracało status 200 dla błędów
  33. 33. 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
  34. 34. REST, obsługa błędów 400 Bad Request 401 Unauthorized (np. problem z autoryzacją OAuth) 403 Forbidden (uprawnienia lub przekroczony limit) 404 Not Found 406 Not Acceptable
  35. 35. REST, obsługa błędów 410 Gone (podana wersja api nie jest wspierana) 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)
  36. 36. REST, obsługa błędów 400 Bad Request 401 Unauthorized (np. problem z autoryzacją OAuth) 403 Forbidden (uprawnienia lub przekroczony limit) 404 Not Found 405 Method Not Allowed (GET zamiast POST,..)
  37. 37. REST, obsługa błędów 400 Bad Request 404 Not Found
  38. 38. REST, obsługa błędów 400 Bad Request 404 Not Found 422 Unprocessable Entity (problem z weryfikacją)
  39. 39. REST, limity X-Rate-Limit-Limit (limit dla danego zapytania) X-Rate-Limit-Remaining (dostępna pula, 15 min okno) X-Rate-Limit-Reset (czas odnowienia limitu)
  40. 40. REST, limity X-RateLimit-Limit (limit dla danego zapytania) X-RateLimit-Remaining (dostępna pula) X-RateLimit-Reset (czas odnowienia limitu) GET /rate_limit
  41. 41. REST, limity https://www.linkedin.com/secure/developer? showthrottles=&app_id=appId&app_name=appName status 403 z informacją o „throttle limit”
  42. 42. REST, limity Error, Code: 17, User request limit reached Error, Code: 4, Application request limit reached
  43. 43. 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
  44. 44. HATEOAS Przykład (reponse body) { curl https://api.github.com { "current_user_url": „https://api.github.com/user", "emails_url": „https://api.github.com/user/emails", "events_url": „https://api.github.com/events", "feeds_url": „https://api.github.com/feeds", "issues_url": "https://api.github.com/issues" }
  45. 45. HATEOAS Przykład (nagłówki) { curl https://api.github.com/users?access_token=token Link: <https://api.github.com/users? access_token=token&since=135>; rel="next", <https:// api.github.com/users{?since}>; rel="first"
  46. 46. HATEOAS http://blog.perfectapi.com/2012/opinionated-rpc-apis-vs-restful-apis/
  47. 47. Dokumentacja Potrzebna nam jeszcze dokumentacja ? http://swagger.wordnik.com/
  48. 48. Dokumentacja Jak dobrze, że mogę przetestować API https://dev.twitter.com/console https://developers.facebook.com/tools/explorer
  49. 49. Dokumentacja 49
  50. 50. Dokumentacja 50
  51. 51. Dokumentacja Dostęp do API z innej „domeny” Access-Control-Allow-Origin: * (github pozwala ustawić domenę) Access-Control-Allow-Methods: GET, POST, DELETE, PUT Access-Control-Allow-Headers: Content-Type, Authorization, access_token
  52. 52. SDK Jak mogę wam pomóc w integracji? Pozwala ukryć błędy projektowe API Dostarcza obiekty zapytań i odpowiedzi Dostarcza interfejs API Wsparcie dla obsługi błędów
  53. 53. SDK https://developer.linkedin.com/documents/libraries-and-tools oficjalne SDK tylko dla javascript wsparcie w różnych framework’ach (community)
  54. 54. SDK http://developer.github.com/v3/libraries oficjalne SDK (octokit) dla c#, ruby, go i obj-c
  55. 55. SDK oficjalne SDK dla iOS, Android, javascript, php, unity olbrzymie wsparcie w projektach community
  56. 56. SDK https://dev.twitter.com/docs/twitter-libraries oficjalne SDK hbc dla java (streaming api, not REST) olbrzymie wsparcie w projektach community
  57. 57. Uwagi Pola id zwracaj jako typu znakowego "id": 187462027801919500, "id_str": "187462027801919489" Światowy standard formatowanie daty (ISO-8601) http://apiux.com/2013/03/20/5-laws-api-dates-and-times Unikajmy magicznych wartości price = -1 Proste rzeczy w przedstawiaj w prosty sposób
  58. 58. Uwagi Definiowanie akcji na zasobach czasowniki dla akcji lub nowy zasób (rzeczownik) Przyjęta notacja dla nazwa parametrów camelCase Stronicowanie wyników limit i offset zamiast page Unikaj domyślnych wartości dla parametrów
  59. 59. Uwagi Nie pozwalaj na znikające pola w odpowiedzi Przyjmowanie rozbudowanych danych wejściowych w metodzie GET
  60. 60. Zagadka Czy można wysłać metodą GET dane w body? curl -X GET --data '{"id": "2223"}' http://echo.200please.com -H "Content-type: application/json" GET / HTTP/1.0 Host: echo.200please.com Connection: close Content-Length: 14 User-Agent: curl/7.34.0 Accept: */* Content-type: application/json ! {"id": "2223"}
  61. 61. { Ciekawy temat, chcę więcej! ! ! http://blog.steveklabnik.com/posts/2011-08-07-some-peopleunderstand-rest-and-http http://blog.steveklabnik.com/posts/2011-07-03-nobodyunderstands-rest-or-http http://www.informit.com/articles/article.aspx?p=1566460 http://blog.perfectapi.com/2012/opinionated-rpc-apis-vsrestful-apis/ ! http://info.apigee.com/Portals/62317/docs/web%20api.pdf ! http://apiux.com/2013/03/20/5-laws-api-dates-and-times
  62. 62. Warsztaty https://github.com/Zenedith/swagger-jersey2-gradle-demo-app gradle swagger jersey2 jetty
  63. 63. Pytania ?
  64. 64. Dziękuję za uwagę

×