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

1. !
Budowa RESTowego api w oparciu o HATEOAS
v1.1 braincode@2014
mateusz.stepniak@allegro.pl

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

3. API
application
programming
interface

4. API
punkt
wejścia
usługi

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

6. API
Dla KOGO?
biznes
deweloper
klient

7. API
A gdy nie ma API..
powstają nieskalowalne, drogie w utrzymaniu monolity
ograniczamy liczbę klientów (mobilni, tv, agd, ..)

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
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. 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. Autoryzacja
OAuth 2.0

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. 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. Autoryzacja
OAuth 2.0
Application-only authentication (kontekst aplikacji)
https://dev.twitter.com/docs/auth/application-only-auth

15. REST jest wzorcem architektury
REST
representational
state
transfer

16. REST jest wzorcem architektury
REST
reprezentacja
zasobów
usługi

17. REST
reprezentacja
zasoby
jednorodny interfejs
bez stanu

18. REST, reprezentacja
JSON (ECMA-404)
{
{
"id": "7",
"category": {
"id": "4",
"name": "Lions"
}
}

19. REST, reprezentacja
XML
{
<response>
<id>7</id>
<category>
<id>4</id>
<name>Lions</name>
</category>
</response>

20. REST, reprezentacja
Poproszę te dane jako..
/posts/1?format=json
/posts/1.xml
Accept: application/json
Accept: application/vnd.github.beta+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 (unikajmy abstrakcji)

23. REST, zasoby
Przykłady
/events
/repos/:owner/:repo/events
/feeds
/statuses
/notifications

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. 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. 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. 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. 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. REST, zasoby
Partial response, czyli potrzebuję tylko..
Definicja podzbioru pól w odpowiedzi z API
parametr fields=field1,field2
:(field1,field2,field3...)

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. 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. 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. 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. 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. 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. 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. REST, obsługa błędów
400 Bad Request
404 Not Found

38. REST, obsługa błędów
400 Bad Request
404 Not Found
422 Unprocessable Entity (problem z weryfikacją)

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. 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. REST, limity
https://www.linkedin.com/secure/developer?
showthrottles=&app_id=appId&app_name=appName
status 403 z informacją o „throttle limit”

42. REST, limity
Error, Code: 17, User request limit reached
Error, Code: 4, Application request limit reached

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. 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. 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. HATEOAS
http://blog.perfectapi.com/2012/opinionated-rpc-apis-vs-restful-apis/

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

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

49. Dokumentacja
49

50. Dokumentacja
50

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. 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. SDK
https://developer.linkedin.com/documents/libraries-and-tools
oficjalne SDK tylko dla javascript
wsparcie w różnych framework’ach (community)

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

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

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

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. 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. Uwagi
Nie pozwalaj na znikające pola w odpowiedzi
Przyjmowanie rozbudowanych danych wejściowych
w metodzie GET

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. {
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. Warsztaty
https://github.com/Zenedith/swagger-jersey2-gradle-demo-app
gradle
swagger
jersey2
jetty

63. Pytania ?

64. Dziękuję za uwagę