REST API w node.js z HapiJS – pierwsza aplikacja • Type of Web

Wymagane jest podstawowa znajomość node.js i npm.

HapiJS

Od dłuższego czasu zajmuję się tworzeniem back-endu w node.js. Bardzo przypadł mi do gustu szczególnie framework HapiJS i od tamtej pory wykorzystywałem go praktycznie we wszystkich projektach. Jakie są jego główne zalety?

Prostota HapiJS

HapiJS w szczególności cechuje prostota. Bardzo łatwo postawić w nim całkowicie funkcjonalne REST API. Nie musimy przebijać się przez gąszcz dokumentacji – wystarczy przejrzeć przykład lub dwa i już możemy zacząć pisać samodzielnie. Bez wątpienia to ogromna zaleta.

HapiJS jest proste, ale nie prostackie. Pierwsze kroki postawić łatwo, ale nie oznacza to, że na tym możliwości tego frameworka się kończą. Jest świetnym narzędziem o ogromnym potencjale! Hapi daje nam takie możliwości jak:

tworzenie REST API
renderowanie szablonów
obsługa sesji i ciastek
tworzenie proxy
walidacja formularzy
uwierzytelnianie i autoryzacja
obsługa formularzy i przesyłania plików
monitorowanie serwera

A także wiele, wiele innych! Zachęcam do zgłębienia dokumentacji Hapi.

Konwencje

Całkiem nieźle jak na pozornie prostą bibliotekę, prawda? Do tego muszę wspomnieć, że HapiJS nie narzuca właściwie żadnych konwencji. Oczywiście, pewne rzeczy są sugerowane, jednak nie jesteśmy do niczego zmuszani. Kod możemy ułożyć jak nam się podoba, architektura może być totalnie dowolna, podobnie nazewnictwo plików i struktura folderów.

Dzięki temu HapiJS świetnie sprawdzi się do budowania zarówno monolitycznych aplikacji renderujących HTML, jak i do tworzenia microservice’ów.

Przygotowanie do pracy

Tworzenie każdej aplikacji w node.js warto rozpocząć od polecenia npm init. Program zada nam kilka kontrolnych pytań, a następnie wygenerowany zostanie plik package.json. Większość pytań możemy po prostu pominąć:

Następnie możemy zainstalować już HapiJS przy pomocy:

npm install hapi --save

To polecenie nie tylko pobierze framework do folderu node_modules, ale również zapisze zależność w pliku package.json (warto tam zajrzeć). Stwórzmy jeszcze pusty plik index.js i jesteśmy gotowi do dalszej pracy!

Pierwsze spotkanie z HapiJS

HapiJS jest frameworkiem, w którym postawiono na konfigurację i deklaratywną składnię. W teorii oznacza to, że opisujemy co, a nie jak. W praktyce praca z Hapi sprowadza się do tworzenia prostych JavaScriptowych obiektów, które w prosty sposób opisują np. endpointy, ciastka czy uwierzytelnianie.

Serwer

Przejdźmy od słów do czynów. Edytujemy nasz jedyny plik: index.js i piszemy w nim:

'use strict';
const Hapi = require('hapi');
const server = new Hapi.Server();
server.connection({
host: 'localhost',
port: 3000
});
server.start((err) => {
if (err) {
throw err;
}
console.log(`Server running at ${server.info.uri}`);

});

W powyższym przykładzie zaczynamy od stworzenia serwera w Hapi. Następnie musimy zadeklarować tzw. połączenie (connection), aby framework wiedział w jaki sposób ma być widoczny ze świata zewnętrznego.

Do server.connection(…) możemy przekazać kilka różnych parametrów, jednak na razie interesują nas tylko dwa: host i port, które składają się na adres, pod którym ma być dostępny nasz serwer.

Następnie wywołujemy funkcję server.start(…), która powoduje uruchomienie serwera w Hapi. Funkcja ta przyjmuje callback jako argument – w nim warto sprawdzić czy nie było żadnego błędu (if (err) …). W końcu, wyświetlamy w konsoli informację o tym pod jakim adresem dostępny jest nasz serwer.

Aplikację możemy uruchomić wpisując w terminalu node index.js. Warto zauważyć, że naszym oczom ukazuje się adres składający się z wcześniej podanego hosta oraz numeru portu:

Endpointy

Jeśli teraz spróbujemy otworzyć adres widoczny na ekranie, czyli http://localhost:3000 to zobaczymy błąd wygenerowany przez Hapi: Błąd Hapi

Oznacza to, że serwer działa, jednak Hapi nie wie jeszcze co ma zrobić, gdy otwarta zostanie ścieżka /. Musimy zadeklarować endpoint! Wspomnę tylko, że w polskiej literaturze nazywa się to końcówka, ale nikt tak nie mówi. Naprawdę!

Endpoint definiujemy poprzez funkcję server.route. Wymagane są trzy parametry: path czyli ścieżka, method czyli metoda HTTP oraz handler, który w tym przypadku będzie funkcją. Poniższy kod dodajemy przed server.start(…):

server.route({  
    method: 'GET',
    path: '/',
    handler(request, reply) {
        reply('Hello, world!');
    }
});

Funkcja handler zostanie wywołana przez Hapi gdy użytkownik odwiedzi podaną ścieżkę. Do handlera przekazywane są dwa argumenty – pierwszy z nich jest obiektem z informacjami o żądaniu, natomiast drugi to specjalna funkcja, dzięki której możemy coś łatwo i szybko zwrócić.

Po każdej zmianie w pliku index.js musimy ponownie uruchomić serwer, aby zmiany były widoczne w przeglądarce.

Podsumowanie

Udało nam się stworzyć prosty back-end w node.js przy pomocy frameworka HapiJS. Utworzyliśmy serwer i połączenie oraz zadeklarowaliśmy pierwszy endpoint, którego zadaniem było wyświetlenie komunikatu.

Cały kod dostępny jest na moim GitHubie: https://github.com/mmiszy/hapijs-tutorial/tree/czesc-1

W kolejnej części opowiem trochę o obsługiwaniu parametrów i zapytań (query string). Powiem też o bardzo fajnej możliwości, jaką daje nam Hapi: automatycznej walidacji żądań.