Czym jest usługa sieciowa (web service)?

Usługa sieciowa (web service) to interfejs, przez który aplikacje wymieniają dane lub wywołują funkcje przez sieć. Strona WWW jest przeznaczona przede wszystkim do czytania i obsługi przez ludzi, a usługa sieciowa udostępnia kontrakt przeznaczony dla programów-klientów. Jeden produkt może oferować jedno i drugie. Wiele usług korzysta z HTTP i JSON, ale pojęcie obejmuje też inne protokoły i formaty danych.

Jak działa żądanie i odpowiedź

Klient wysyła żądanie do określonego punktu końcowego (endpointu), podając metodę, parametry i – jeśli trzeba – dane uwierzytelniające. Usługa sprawdza żądanie, wykonuje operację i zwraca odpowiedź. W API opartych na HTTP kody statusu rozróżniają ogólny wynik: powodzenie, problem po stronie klienta (np. nieprawidłowe dane wejściowe) albo błąd po stronie serwera. Treść odpowiedzi zawiera zwykle szczegóły w udokumentowanym formacie.

Przejrzysty kontrakt opisuje ścieżki, metody, pola, typy, uwierzytelnianie, limity zapytań i sytuacje błędów. Dzięki niemu klientów można rozwijać niezależnie od usługi. Wersjonowanie ma znaczenie, bo zmiana pola lub jego interpretacji może zepsuć istniejące aplikacje, nawet jeśli adres endpointu się nie zmienia. Zachowuj zgodność wsteczną tam, gdzie ją obiecano, i publikuj okresy wycofywania funkcji.

Popularne style interfejsów

REST to styl architektury, a nie jeden konkretny format przesyłania danych. API określane jako RESTful zwykle reprezentują zasoby za pomocą adresów URL i używają metod takich jak GET do odczytu oraz POST lub PUT do zmian. Żądanie GET nie powinno trwale zmieniać stanu, bo klienci i pośrednicy mogą je powtarzać lub buforować. SOAP, stosowany w wielu systemach korporacyjnych, używa ustrukturyzowanych komunikatów XML i formalnych opisów usług.

GraphQL pozwala klientom pobierać określony zestaw pól zgodnie ze schematem, często przez HTTP. Może ograniczyć przesyłanie zbędnych danych, ale komplikuje kwestie kosztu zapytań, autoryzacji i buforowania. Webhooki odwracają typowy schemat odpytywania: jedna usługa wywołuje zarejestrowany endpoint, gdy zajdzie zdarzenie. Wymagają uwierzytelniania nadawcy, obsługi ponowień i ochrony przed wielokrotnym dostarczeniem. Żadne z tych podejść nie jest najlepsze w każdej sytuacji.

Bezpieczeństwo i prywatność

Używaj HTTPS do ochrony przesyłanych danych i weryfikuj certyfikat serwera. Uwierzytelniaj wywołujących odpowiednim mechanizmem i osobno autoryzuj każdą operację oraz każdy obiekt. Ważny token potwierdza tylko to, na co pozwala jego zakres; nie sprawia, że dowolne dane wejściowe stają się bezpieczne. Sprawdzaj rozmiar i typy danych w żądaniach, nie ujawniaj prywatnych informacji w komunikatach o błędach i ustaw limity chroniące przed nadużyciami.

Sekrety nie powinny trafiać do publicznych adresów URL, kodu po stronie klienta ani logów. Ujawnione dane uwierzytelniające wymieniaj, ograniczaj ich zakres i stosuj osobne dane dla środowiska produkcyjnego i testowego. W API przyjmujących adres URL wywołania zwrotnego (callback) weryfikuj adresy docelowe, aby nie dopuścić do żądań kierowanych do sieci wewnętrznych. Udokumentuj, jakie dane osobowe zwraca usługa, i przechowuj tylko to, co niezbędne.

Niezawodność i wydajność

Sieci zawodzą, dlatego klienci potrzebują limitów czasu, ograniczonej liczby ponowień i przemyślanej obsługi częściowych awarii. Odczyt można bezpiecznie powtórzyć, ale ponowienie płatności czy innej operacji zmieniającej dane wymaga mechanizmu idempotentności, aby uniknąć duplikatów. Paginacja ogranicza duże zbiory wyników. Buforowanie może zmniejszyć obciążenie przy stabilnych danych publicznych, natomiast szybko zmieniające się lub prywatne odpowiedzi wymagają starannie dobranej polityki cache.

Operatorzy powinni mierzyć opóźnienia, odsetek błędów i dostępność na rzeczywistej ścieżce klienta. Serwer zwracający HTTP 200 może mimo to oddać niepełne lub bezużyteczne dane, więc monitoruj również oczekiwane efekty biznesowe. Limity zapytań chronią usługę, ale powinny być komunikowane w przewidywalny sposób. Jeśli usługa jest ważna dla użytkowników, zapewnij stronę statusu lub kanał wsparcia na czas incydentów.

Wybór lub budowa usługi

Zacznij od zadania użytkownika i kontraktu danych, a potem wybierz styl interfejsu, który klienci będą w stanie zaimplementować, a zespół utrzymać. Przetestuj prawidłowe odpowiedzi, błędne dane wejściowe, wygasłe dane uwierzytelniające, uprawnienia, paginację i przekroczenia czasu. Dbaj o aktualność przykładów i pokazuj konkretne błędy. Integrując usługę zewnętrzną, zapoznaj się z jej limitami, zasadami dotyczącymi danych i zapowiedziami zmian; wygodny endpoint to nadal zależność, która może zawieść.