Restify

Prezentacja i omówienie możliwości frameworku Restify do tworzenia RESTful webservices w oparciu o Node.js.

Transcript

1. Restify moduł Node.js do tworzenia webserwisów REST Adam Jodłowski
2. 2 Co to jest Node.js?
3. 3 Node.js • środowisko uruchomieniowe JavaScript na serwerze • przeznaczone dla nowoczesnych aplikacji nastawionych na bogatą interakcję z klientem • zorientowane na zdarzenia (event loop) • jednowątkowość wymusza nieblokujące operacje I/O • podstawą projektu jest silnik JavaScript Google V8, kilka wbudowanych bibliotek i moduły użytkowników • implementuje ECMAScript 5, część standardu CommonJS i dostarcza konsolę REPL
4. 4 Co to jest REST?
5. 5 REpresentational State Transfer • paradygmat tworzenia usług klient-serwer zainspirowany sposobem działania protokołu HTTP • opiera się na pojęciu reprezentacji zasobu i możliwych do wykonania na nim metod zmieniających jego stan • główne cechy • architektura klient-serwer • zorientowanie na zasoby • jednolity interfejs • bezstanowość
6. 6 Do rzeczy
7. 7 Restify v1.3 • moduł Node.js ułatwiający tworzenie poprawnych usług sieciowych zgodnych z paradygmatem REST • opracowany z myślą o lepszej kontroli nad HTTP niż dają to frameworki webowe (np. Express) • zawiera szereg udogodnień (wersjonowanie, sumy kontrolne, filtry) dla tworzenia tzw. strict APIs
8. 8 Instalacja i uruchomienie $ npm install restify var restify = require('restify'); var server = restify.createServer(); server.listen(8080, function() { console.log('%s listening at %s', server.name, server.url); }); function respond(req, res, next) { res.send('hello ' + req.params.name); } server.get('/hello/:name', respond); $ node server.js restify listening at http://0.0.0.0:8080
9. 9 Sprawdzenie, czy działa $ curl -is http://localhost:8080/hello/adamus -H 'Accept: text/plain' HTTP/1.1 200 OK Access-Control-Allow-Origin: * Access-Control-Allow-Headers: Accept, Accept-Version, Content-Length, Content- MD5, Content-Type, Date, X-Api-Version Access-Control-Expose-Headers: X-Api-Version, X-Request-Id, X-Response-Time Server: restify X-Request-Id: 06ace5a0-87ab-4faf-b76c-9a9a35682937 Access-Control-Allow-Methods: GET Connection: close Content-Length: 12 Content-MD5: TNyTQnhx7KlWEKi+aTn9zA== Content-Type: text/plain; charset=UTF-8 Date: Thu, 15 Mar 2012 12:24:49 GMT X-Response-Time: 3 hello adamus // domyślny Content-Type to application/json
10. 10 Przegląd możliwości
11. 11 Konfiguracja i wspólne handlery żądań Obiekt konfiguracyjny używany przy tworzeniu serwera var fs = require('fs'); var options = { certificate: fs.readFileSync('certificate.crt'), key: fs.readFileSync('private.key'), name: 'Restify Server 1.0', version: '1.0.0', // X-Api-Version: 1.0.0 formatters: { 'format': function() { ... } } }; var server = restify.createServer(options); Obsługa żądań przed lub po wywołaniu metod rutingu server.pre(function (req, res, next) { // server.pre([f1, f2, ...]); // przetwarzanie ... return next(); }); // kolejność wywołania zależna od kolejności rejestracji względem rutingu server.use(function (req, res, next) { ... });
12. 12 Ruting Ruting oparty jest o metody dostępu i ścieżki zasobów, parametry w formie URL-encoded lub JSON są automatycznie parsowane server.get('/posts/:id', function (req, res, next) { console.log('post id = ' + req.params.id); res.send(200, {author: 'adamus', content: 'this is a post'}); return next(); }); $ curl http://localhost:8080/posts/8 {"author":"adamus","content":"this is a post"} // komunikat konsoli serwera: post id = 8 Pozostałe metody obsługujemy analogicznie server.post(...); server.put(...); server.del(...); server.head(...); W miejsce ścieżki możemy przekazać obiekt RegExp a dopasowania kolejnych grup otrzymamy w req.params[0], req.params[1] itd.
13. 13 Wersjonowanie rutingu Protokół HTTP nie definiuje sposobu wersjonowania RESTfulowych API, przyjęto zatem rozwiązanie Semantic Versioning (SemVer) server.get({path: '/posts/:id', version: '2.0.1'}, function (req, res, next) { ... }); server.get({path: '/posts/:id', version: '1.2.3'}, function (req, res, next) { ... }); $ curl localhost:8080/posts/8 -H 'Accept-Version: 1' // otrzymamy wersję 1.2.3 $ curl localhost:8080/posts/8 // otrzymamy pierwszą zarejestrowaną wersję, czyli 2.0.1 $ curl localhost:8080/posts/8 -H 'Accept-Version: 3' HTTP/1.1 400 Bad Request {"code":"InvalidVersion","message":"GET /posts/8 supports versions: 2.0.1, 1.2.3"} W powyższych ścieżkach możemy podać tablice kolejnych wersji W taki sam sposób działa parametr version całego serwera, ale dotyczy wszystkich ścieżek, którym nie nadano wersji (pełni rolę domyślną)
14. 14 Negocjacja reprezentacji treści Wysyłając odpowiedź metodą send() wartość nagłówka Content-Type może być ustalona automatycznie na podstawie dostępnych formaterów, wbudowano obsługę application/octet-stream*, application/json i text/plain Własne formatery treści podajemy w konfiguracji serwera formatters: { 'application/my-format': function (req, res, body) { // logika konwersji formatu return reprezentacja_body; } // kolejne formatery ... } Wysyłając żądanie z określonym formatem w nagłówku Accept, zostanie odesłana postać zwrócona w funkcji obsługi tego formatu Obsługiwane przez serwer formaty znajdują się w tablicy server.acceptable
15. 15 Obsługa błędów Nieobsłużone błędy powodują zwrócenie kodu 500 Możemy zwracać błędy pierwszym argumentem liczbowym metody send() oraz korzystać z obiektu Error('wiadomość') res.send(401, new Error('Nie masz uprawnień')); Restify posiada zestaw symbolicznych błędów HttpError i RestError (niestandardowe błędy z dodatkowym opisem w postaci JSON) return next(new restify.ConflictError("Żądanie jest konfliktowe")); // HttpError return next(new restify.InvalidArgumentError("Niepoprawny argument")); // RestError // obie instrukcje zwrócą kod 409
16. 16 Zdarzenia rozgłaszane (EventEmitter) Restify rozgłasza standardowe zdarzenia z modułu http.Server Node.js oraz własne, takie jak: • 'NotFound' • 'MethodNotAllowed' • 'VersionNotAllowed' • 'after' • 'uncaughtException' Nasłuchujemy na zdarzenia przez server.on('zdarzenie', funkcja_obsługi(...) { ... });
17. 17 Wbudowane pluginy Restify dostarcza kilka pluginów do przetwarzania żądań • AcceptParser • QueryParser • BodyParser • Throttle (token bucket) • ConditionalRequest • ETag / If-None-Match • LastModified / If-Modified-Since • AuditLogger
18. 18 Obiekt żądania Do standardowych właściwości z http.ServerRequest (method, url, headers) Restify dodaje własne .header('Authorization') – pobranie wartości nagłówka .accepts('text/plain') – czy żądanie akceptuje format .is('application/json') – czy żądanie jest danego typu .contentLength, .contentType .id – UUID żądania .time – czas dotarcia do serwera .secure – czy żądanie przyszło w sesji SSL
19. 19 Obiekt odpowiedzi Do standardowych właściwości z http.ServerResponse (statusCode, get/set/removeHeader) Restify dodaje własne .header('X-My-Header', '...') – ustawienie wartości nagłówka .cache(typ, opcje) – ustawienie nagłówka Cache-Control .status(200)/.code – ustawienie kodu odpowiedzi .contentLength, .contentType .charSet – kodowanie dopisywane do Content-Type .id – UUID żądania Możemy nadpisać domyślnie odsyłane nagłówki i ich treść restify.defaultResponseHeaders = function(data) { this.header('Server', 'Mój serwer'); }; // this to obiekt odpowiedzi a data to gotowe do wysłania ciało (response body)
20. 20 Bonus: strona kliencka
21. 21 Restify Client Moduł kliencki pozwala konsumować usługi sieciowe • JsonClient • wysyła i odbiera wiadomości w formacie JSON • StringClient • wysyła Url-Encoded i odbiera czysty tekst, na przykład XML • HttpClient • umożliwia pracę ze strumieniami danych na poziomie oferowanym przez moduły http/https Node.js Konfiguracja żądań obejmuje metodę dostępu, nagłówki, czas timeoutu, liczbę powtórzeń wywołania itp.
22. 22 Same zalety?
23. 23 Problemy z Restify • Nieaktualna i niedokładna dokumentacja • Brak obsługi niestandardowych metod HTTP • Brak negocjacji Accept-Charset, -Encoding*, -Language • Brak obsługi nietrywialnych metod autoryzacji • Niespójne API Rozwiązanie? Fork me on GitHub
24. 24 Dla zainteresowanych
25. 25 Warto poczytać • Just what is Node.js? http://www.ibm.com/developerworks/opensource/library/os-nodejs/ • What is Node.js? http://radar.oreilly.com/2011/07/what-is-node.html • Nobody Understands REST or HTTP http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http • Some People Understand REST and HTTP http://blog.steveklabnik.com/posts/2011-08-07-some-people-understand-rest-and-http • How I Explained REST to My Wife http://tomayko.com/writings/rest-to-my-wife • Restify documentation http://mcavage.github.com/node-restify/ • RESTful Web Services Cookbook Subbu Allamaraju, O’Reilly 2010, Yahoo! Press