!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 Pytania

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, 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)

OAuth 2.0

Autoryzacja

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 jest wzorcem architektury

REST

representational state transfer

REST jest wzorcem architektury

REST

reprezentacja zasobów usługi

REST

zasoby

jednorodny interfejs

bez stanu

reprezentacja

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: 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

Przykłady/events

/repos/:owner/:repo/events

/notifications

/feeds

/statuses

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,..)

400 Bad Request

REST, obsługa błędów

404 Not Found

400 Bad Request

REST, obsługa błędów

404 Not Found

422 Unprocessable Entity (problem z weryfikacją)

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

Dokumentacja

�49

Dokumentacja

�50

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

Pytania ?

Dziękuję za uwagę