Interfejsy internetowe w głębi — HTTP, REST i kody stanu

Gdy frontend, aplikacja mobilna lub obcy system pobiera lub zapisuje dane z twojego backendu, odbywa się to przez API. Na sieci zdecydowana większość interfejsów API opiera się na HTTP — ten sam protokół, którego przeglądarka używa do pobierania stron. Jeśli dobrze rozumiesz HTTP, rozumiesz fundamenty prawie wszelkiej komunikacji internetowej, nie tylko interfejsów API.

HTTP jest zbudowany na założeniu, że klient wysyła żądanie, a serwer wysyła odpowiedź. Żądanie ma metodę (co chcę zrobić), ścieżkę (na czym chcę to zrobić), opcjonalne nagłówki (metadane) i może treść z danymi. Odpowiedź ma kod statusu (czy poszło dobrze), nagłówki i zazwyczaj treść z wynikiem — w API sieciowym często w formacie JSON. Każde żądanie jest z natury samodzielne; serwer nic nie pamięta między nimi, chyba że świadomie go zbudujesz, np. z sesją lub tokenem.

Metody HTTP (zwane również verbami) mówią, co chcesz zrobić. Używanie ich zgodnie z ich znaczeniem czyni API przewidywalnym. Ważną właściwością jest, czy metoda jest bezpieczna (nie zmienia danych) i idempotentna (ten sam kall powtórzony daje ten sam stan) — to określa, czy bezpieczne jest powtórzenie kalla, który być może nie dotarł.

REST to rozpowszechniony styl dla interfejsów API internetowych. Podstawowa idea to myślenie w kategoriach zasobów — rzeczy, które mają adres — zamiast działań. Zamiast punktu końcowego takiego jak 'createUser' masz zasób 'users', na którym używasz metod: pobierz listę, utwórz nową, pobierz konkretną, zaktualizuj ją, usuń ją. Adresy są nazwane po rzeczach (rzeczowniki, najlepiej liczba mnoga), a metoda określa akcję. To daje interfejs API, który jest łatwy do zgadnięcia i spójny w użyciu.

Kod statusu w odpowiedzi krótko mówi, jak poszło. Są pogrupowane w serie, a to serie, które powinieneś przede wszystkim znać: seria 2 oznacza sukces, seria 3 oznacza przekierowanie, seria 4 oznacza błąd po stronie klienta (wysłałeś coś nieprawidłowo), a seria 5 oznacza błąd na serwerze. Używanie prawidłowego kodu jest częścią umowy — klient musi być w stanie zareagować prawidłowo bez zgadywania.

• 01Seria 2: udało się — np. utworzono lub pobrano
• 02seria 3: klient musi gdzieś indziej
• 03Seria 4: klient zrobił coś źle — np. nieprawidłowe dane wejściowe, niezalogowany, brak dostępu, nie znaleziono
• 04Seria 5: serwer zawiódł — to nie wina klienta

Gdy inni budują na twoim API, to umowa: jeśli gwałtownie to zmienisz, złamiesz ich systemy. Dlatego versjonuje się API, aby nowa wersja mogła się pojawić, podczas gdy stara nadal pracuje dla tych, którzy nie są gotowi do przełączenia. Udokumentuj umowę — jakie adresy istnieją, jakie pola są oczekiwane, co się odpowiada — aby inni mogli użyć API bez czytania Twojego kodu źródłowego lub zgadywania.

API to drzwi do twoich danych, często bez interfejsu użytkownika, aby coś ukryć. Dlatego pełne bezpieczeństwo sieci ma zastosowanie: wymagaj logowania i sprawdź dostęp przy każdym połączeniu, sprawdź wszystkie dane wejściowe na serwerze, użyj szyfrowania podczas transportu i rozważ ograniczenie liczby połączeń, które klient może wysłać, aby API nie mogło być przytłoczone. Otwarty, nieudokumentowany i nienadzorowany interfejs API to oczywisty cel.

“Dobre API można używać bez czytania leżącego za nim kodu — metoda, adres i kod statusu mówią prawie wszystko.”

— Zwykła zasada w projektowaniu API