!Budowa RESTowego api w oparciu o HATEOAS
v1.1 braincode@2014 [email protected]
{ Agenda, czyli o tym, co będzie !API (WEBAPI) REST HATEOAS Różnice w API Github, Facebook, Twitter i Linkedin Uwagi Pytania
API
A gdy nie ma API..
powstają nieskalowalne, drogie w utrzymaniu monolity
ograniczamy liczbę klientów (mobilni, tv, agd, ..)
API
Hackathon, czyli „sprzedajemy” nasze API (jako startup)
http://www.hackathon.io/https://www.hackerleague.org/hackathons
API
Bezpieczeństwo jest najważniejsze
cały ruch po HTTPS
użycie OAUTH 2.0
separacja danych od autoryzacji (w nagłówku)
nie wymyślajmy autoryzacji na nowo..
problem root (android) i jailbreak (iOS)
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)
Autoryzacja
OAuth 2.0
Basic Authentication
Personal Access Tokenscurl -u „login:pass" https://api.github.com/repos/user/repo
curl https://api.github.com/user?access_token=cb4sssdsdsdsd
Autoryzacja
OAuth 2.0
appsecret_proof (dodatkowo zabezpiecza token)
tokeny z krótkim i długim czasem życia
https://developers.facebook.com/docs/graph-api/securing-requests/
Autoryzacja
OAuth 2.0
Application-only authentication (kontekst aplikacji)
https://dev.twitter.com/docs/auth/application-only-auth
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: application/vnd.github.beta+json
REST, reprezentacja
Ale dlaczego to tyle waży?
klient: Accept-Encoding: gzip, deflate
serwer: Content-Encoding: gzip
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 (unikajmy abstrakcji)
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)
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
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
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
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
REST, zasoby
Partial response, czyli potrzebuję tylko..
Definicja podzbioru pól w odpowiedzi z API
parametr fields=field1,field2
:(field1,field2,field3...)
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
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
REST, obsługa błędów
Czy status 200 dla błędów może się przydać ?
suppress_response_codes=truekiedyś zwracało status 200 dla błędów
Tak, aplikacje flash
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
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
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)
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,..)
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)
X-RateLimit-Limit (limit dla danego zapytania)
X-RateLimit-Remaining (dostępna pula)
X-RateLimit-Reset (czas odnowienia limitu)
GET /rate_limit
REST, limity
https://www.linkedin.com/secure/developer?showthrottles=&app_id=appId&app_name=appName
REST, limity
status 403 z informacją o „throttle limit”
Error, Code: 17, User request limit reached
REST, limity
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 API
nagłówki content-type i accept
HATEOAS
Przykład (reponse body)
{ { "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" }
curl https://api.github.com
HATEOAS
Przykład (nagłówki)
{Link: <https://api.github.com/users?access_token=token&since=135>; rel="next", <https://api.github.com/users{?since}>; rel="first"
curl https://api.github.com/users?access_token=token
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/explorer
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
Dokumentacja
SDK
Dostarcza obiekty zapytań i odpowiedzi
Pozwala ukryć błędy projektowe API
Dostarcza interfejs API
Wsparcie dla obsługi błędów
Jak mogę wam pomóc w integracji?
SDK
https://developer.linkedin.com/documents/libraries-and-tools
oficjalne SDK tylko dla javascript
wsparcie w różnych framework’ach (community)
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 w projektach community
Uwagi
Światowy standard formatowanie daty (ISO-8601)
Unikajmy magicznych wartości
Proste rzeczy w przedstawiaj w prosty sposób
Pola id zwracaj jako typu znakowego
http://apiux.com/2013/03/20/5-laws-api-dates-and-times
price = -1
"id": 187462027801919500,"id_str": "187462027801919489"
Przyjęta notacja dla nazwa parametrów
Stronicowanie wyników
Definiowanie akcji na zasobach
Uwagi
Unikaj domyślnych wartości dla parametrów
limit i offset zamiast page
czasowniki dla akcji lub nowy zasób (rzeczownik)
camelCase
Przyjmowanie rozbudowanych danych wejściowych w metodzie GET
Uwagi
Nie pozwalaj na znikające pola w odpowiedzi
ZagadkaCzy 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"}
{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 !http://apiux.com/2013/03/20/5-laws-api-dates-and-times
Warsztaty
swagger
gradle
jersey2
jetty
https://github.com/Zenedith/swagger-jersey2-gradle-demo-app
Top Related