Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013
3 likes2,892 views
Prezentacja z devfest 2013 http://www.devfest.pl v.1.0 Allegro.pl
Budowa poprawnego i intuicyjnego api REST HATEOAS devfest@2013
- 1. ! Budowa poprawnego i intuicyjnego API na bazie REST i HATEOAS v1.0 devfest@2013 [email protected]
- 2. { Agenda, czyli o tym, co będzie ! API REST HATEOAS Różne podejście w API Github, Facebook, Twitter i Linkedin Uwagi
- 5. API PO co nam API? dostępność skalowalność zasięg
- 7. API A gdy nie ma API.. powstają nieskalowalne, drogie w utrzymaniu monolity ograniczamy liczbę klientów (rynek mobilny, tv, ..)
- 8. API Hackathon, czyli „sprzedajemy” nasze API (jako startup) http://www.hackathon.io/ https://www.hackerleague.org/hackathons
- 9. 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..
- 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)
- 12. Autoryzacja OAuth 2.0 Basic Authentication Personal Access Tokens
- 13. Autoryzacja OAuth 2.0 appsecret_proof (dodatkowo zabezpiecza token) szczegółowa konfiguracja ustawień aplikacji tokeny z krótkim i długim czasem życia
- 14. Autoryzacja OAuth 2.0 Application-only authentication (kontekst aplikacji)
- 15. REST jest wzorcem architektury REST representational state transfer
- 16. REST jest wzorcem architektury REST reprezentacja zasobów usługi
- 18. REST, reprezentacja JSON (ECMA-404) { { "id": "7", "category": { "id": "4", "name": "Lions" } }
- 20. REST, reprezentacja Poproszę te dane jako.. /posts/1?format=json /posts/1.xml Accept: application/json
- 21. REST, reprezentacja Ale dlaczego to tyle waży? klient: Accept-Encoding: gzip, deflate serwer: Content-Encoding: gzip
- 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 (unikaj abstrakcji)
- 23. 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)
- 24. 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
- 25. 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
- 26. 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
- 27. 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
- 28. REST, zasoby Partial response, czyli potrzebuję tylko.. Definicja podzbioru pól w odpowiedzi z API parametr fields=field1,field2 :(field1,field2,field3...)
- 29. 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
- 30. 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
- 31. REST, obsługa błędów Czy status 200 dla błędów może się przydać ? Tak, aplikacje flash i javascript suppress_response_codes=true zwracało status 200 dla błędów
- 32. 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
- 33. 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
- 34. 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)
- 35. 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,..)
- 36. REST, obsługa błędów 400 Bad Request
- 37. REST, obsługa błędów 400 Bad Request 422 Unprocessable Entity (problem z weryfikacją)
- 38. 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)
- 39. REST, limity X-RateLimit-Limit (limit dla danego zapytania) X-RateLimit-Remaining (dostępna pula) X-RateLimit-Reset (czas odnowienia limitu) GET /rate_limit
- 40. REST, limity https://www.linkedin.com/secure/developer? showthrottles=&app_id=appId&app_name=appName status 403 z informacją o „throttle limit”
- 41. REST, limity Error, Code: 17, User request limit reached Error, Code: 4, Application request limit reached
- 42. 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. Dokumentacja Jeśli API jest intuicyjne to po co dokumentacja ? http://swagger.wordnik.com/
- 45. Dokumentacja Jak dobrze że mogę przetestować API https://dev.twitter.com/console https://developers.facebook.com/tools/explorer
- 46. Access-Control-Allow 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
- 47. SDK Jak mogę Ci 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
- 48. SDK https://developer.linkedin.com/documents/libraries-and-tools oficjalne SDK tylko dla javascript wsparcie w różnych framework’ach (community)
- 49. SDK http://developer.github.com/v3/libraries oficjalne SDK (octokit) dla c#, ruby i obj-c
- 50. SDK oficjalne SDK dla iOS, Android, web (javascript, php) olbrzymie wsparcie w projektach community
- 51. SDK https://dev.twitter.com/docs/twitter-libraries oficjalne SDK hbc dla java (nie jest klientem REST) olbrzymie wsparcie w projektach community
- 52. Uwagi Proste rzeczy w przedstawiaj w prosty sposób Światowy standard formatowanie daty i czasu Unikaj magicznych wartości (price = -1) Pola id zwracaj jako typu znakowego (string)
- 53. Uwagi Definiowanie akcji na zasobach (czasowniki) Przyjęta notacja dla nazwa parametrów (cammel case) Znikające pola w odpowiedzi Stronicowanie wyników (limit i offset zamiast page)
- 54. Uwagi Unikaj domyślnych wartości dla parametrów Przyjmowanie rozbudowanych danych wejściowych w metodzie GET
- 55. Zagadka Czy można wysłać metodą GET dane w body?
- 56. { 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
- 57. Pytania ?