!Budowa poprawnego i intuicyjnego API na bazie

REST i HATEOAS

v1.0 devfest@2013 mateusz.stepniak@allegro.pl

{ Agenda, czyli o tym, co będzie !API REST HATEOAS Różne podejście w API Github, Facebook, Twitter i Linkedin Uwagi

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 (rynek mobilny, tv, ..)

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żywaj OAUTH 2.0

separuj dane wejściowe od autoryzacji (w nagłówku)

nie wymyślaj autoryzacji na nowo..

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 Tokens

Autoryzacja

OAuth 2.0

appsecret_proof (dodatkowo zabezpiecza token)

szczegółowa konfiguracja ustawień aplikacjitokeny z krótkim i długim czasem życia

Autoryzacja

OAuth 2.0

Application-only authentication (kontekst aplikacji)

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

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 (unikaj 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

oraz takie, które dodał wczoraj

GET /users/:id/posts?createdTime=08.11.2013

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..Przechowujemy tylko odpowiedź 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=truezwracało status 200 dla błędów

Tak, aplikacje flash i javascript

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

400 Bad Request

REST, obsługa błędów

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

Tekst

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

Dokumentacja

Jeśli API jest intuicyjne to po co dokumentacja ?

http://swagger.wordnik.com/

Dokumentacja

Jak dobrze że mogę przetestować API

https://dev.twitter.com/console

https://developers.facebook.com/tools/explorer

Access-Control-Allow

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

SDK

Dostarcza obiekty zapytań i odpowiedzi

Pozwala ukryć błędy projektowe API

Dostarcza interfejs API

Wsparcie dla obsługi błędów

Jak mogę Ci 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 i obj-c

SDK

oficjalne SDK dla iOS, Android, web (javascript, php)

olbrzymie wsparcie w projektach community

SDK

https://dev.twitter.com/docs/twitter-libraries

oficjalne SDK hbc dla java (nie jest klientem REST)

olbrzymie wsparcie w projektach community

Uwagi

Światowy standard formatowanie daty i czasu

Unikaj magicznych wartości (price = -1)

Pola id zwracaj jako typu znakowego (string)

Proste rzeczy w przedstawiaj w prosty sposób

Przyjęta notacja dla nazwa parametrów (cammel case)

Znikające pola w odpowiedzi

Definiowanie akcji na zasobach (czasowniki)

Uwagi

Stronicowanie wyników (limit i offset zamiast page)

Przyjmowanie rozbudowanych danych wejściowych w metodzie GET

Uwagi

Unikaj domyślnych wartości dla parametrów

Zagadka

Czy można wysłać metodą GET dane w body?

{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

Pytania ?

Dziękuję za uwagę