Klient zatwierdza zamówienie, serwer je zapisuje, po czym połączenie zrywa się, zanim wróci odpowiedź. W takiej sytuacji Web API zwykle pozwala systemom wymieniać dane przez HTTP, ale bez przemyślanych zasad ponowienia żądania klient może utworzyć zamówienie drugi raz.

Dobre API opisuje zachowanie systemu, także wtedy, gdy coś pójdzie nie tak
- HTTP określa, co oznaczają metody, kody odpowiedzi i nagłówki.
- GET służy do odczytu, a POST może uruchomić operację, której bez zabezpieczenia nie należy automatycznie powtarzać.
- OpenAPI opisuje endpointy w formacie, z którego korzystają narzędzia i klienci.
- ASP.NET Core pozwala budować API kontrolerami albo Minimal APIs; wybór zależy od skali i kształtu aplikacji.
- Limity ruchu trzeba dopasować do sposobu wdrożenia. Licznik działający osobno na każdej instancji może dać inny efekt niż wspólny limit.
Web API daje klientom wspólny kontrakt z serwerem
Gdy aplikacja webowa pobiera listę produktów albo wysyła formularz zamówienia, potrzebuje przewidywalnego sposobu rozmowy z serwerem. Web API udostępnia taki interfejs: klient wysyła żądanie HTTP, a serwer odpowiada statusem i zwykle danymi, często zapisanymi jako JSON.
„Kontrakt” oznacza tu więcej niż adres endpointu. Obejmuje metodę, format danych, możliwe odpowiedzi i reguły błędów. Jeśli klient dostaje nieoczekiwany format albo status, może nie wiedzieć, czy powinien ponowić operację, poprosić o poprawę danych czy pokazać komunikat.
W aplikacji .NET serwer może udostępniać zasoby pod adresami takimi jak /api/products lub /api/orders/42. Trzymanie się spójnego nazewnictwa ułatwia orientację, ale o zachowaniu API przesądza przede wszystkim to, co robi każda metoda HTTP.
POST po zerwanym połączeniu może powielić zamówienie
Najbardziej kłopotliwa awaria nie zawsze wygląda jak błąd serwera. Serwer może zapisać zamówienie, lecz odpowiedź nie dociera do klienta. Klient widzi timeout, a więc nie wie, czy zapis się udał.
Przy GET ponowienie odczytu jest zwykle bezpieczne. POST często inicjuje nową operację, więc automatyczne wysłanie go ponownie może stworzyć drugi rekord. Z kolei PUT zastępuje reprezentację zasobu, a DELETE usuwa go; zgodnie z semantyką HTTP skutki wielokrotnego wykonania tych metod są idempotentne, czyli zamierzone działanie pozostaje takie samo jak po jednym żądaniu.
W RFC 9110 opisano semantykę metod HTTP i ograniczenie automatycznych ponowień żądań nieidempotentnych. Gdy operacja biznesowa musi używać POST, można zaprojektować obsługę klucza idempotencji: klient przesyła unikalny identyfikator, a serwer rozpoznaje powtórzenie tej samej operacji zamiast tworzyć kolejne zamówienie. Sam nagłówek niczego jednak nie załatwia, jeśli API nie zapisuje i nie sprawdza klucza po stronie serwera.
Minimal API pasuje do prostego serwisu, kontrolery ułatwiają rozrost
W małym serwisie katalogowym endpoint może mieścić się w kilku liniach, ale wraz z regułami walidacji i autoryzacji takie skróty szybko tracą czytelność. Minimal APIs ograniczają ceremonię przy prostych usługach; kontrolery dają wyraźniejszy podział na klasy i akcje, kiedy endpointów oraz wspólnych konwencji przybywa.
Dokumentacja Microsoftu pokazuje obie drogi tworzenia Web API w ASP.NET Core. Moja praktyczna granica jest prosta: jeśli endpointy są krótkie i aplikacja ma niewiele reguł, zaczynam od Minimal APIs; jeśli wiele endpointów dzieli walidację, filtry i strukturę kontrolerów, wybrałbym kontrolery. Żaden z tych wariantów sam z siebie nie gwarantuje dobrego kontraktu.
Dokument OpenAPI opisuje ścieżki, parametry, modele i odpowiedzi API w postaci możliwej do odczytu przez narzędzia. Dzięki temu można wygenerować interaktywną dokumentację albo klienta, ale opis musi odpowiadać temu, co serwer rzeczywiście zwraca. Nieaktualna specyfikacja jest gorsza niż jej brak, bo daje fałszywe poczucie pewności.
Problem Details porządkuje błędy dla aplikacji i ludzi
Komunikat „coś poszło nie tak” niewiele mówi klientowi, który musi zdecydować, co zrobić dalej. Dobrze zaprojektowana odpowiedź rozdziela status HTTP od szczegółów problemu i nie ujawnia przy tym wyjątków ani danych wewnętrznych serwera.
RFC 9457 definiuje format Problem Details dla błędów HTTP. W ASP.NET Core można go wykorzystać do zwracania spójnego obiektu, na przykład z typem problemu, tytułem i kodem statusu; aplikacja może dodać własne pole z błędami walidacji. Klient może wtedy obsłużyć błąd programowo, a osoba korzystająca z aplikacji zobaczyć zrozumiały komunikat.
Nie każdy przypadek wymaga rozbudowanego opisu. Gdy zasób nie istnieje, odpowiedź 404 może wystarczyć; gdy dane wejściowe są niepoprawne, szczegóły walidacji pomagają wskazać pole do poprawy. Nie zwracaj klientowi treści wyjątku z bazy danych: nazwy tabel i fragmenty zapytań nie są użyteczną instrukcją naprawy.
Limit żądań musi uwzględniać liczbę instancji API
Limit ruchu chroni usługę przed nadmierną liczbą żądań, ale sposób jego naliczania zależy od wdrożenia. Wbudowane w ASP.NET Core ograniczanie ruchu pozwala dzielić klientów na osobne pule, na przykład według identyfikatora użytkownika, adresu IP lub klucza API.
Jeśli jedna instancja obsługuje cały ruch, lokalny licznik może wystarczyć do prostego ograniczenia. Przy kilku instancjach za load balancerem każda może prowadzić własny licznik, więc limit naliczany osobno nie musi odpowiadać wspólnemu limitowi dla całej usługi. Microsoft opisuje partycjonowanie limitów w middleware ASP.NET Core; wybór klucza i architektury powinien wynikać z tego, czy ograniczasz użytkownika, adres, czy całą usługę.
| Sytuacja | Możliwy skutek | Co zrobić |
|---|---|---|
| Jedna instancja i limit dla całej aplikacji | Licznik lokalny może obejmować wszystkie żądania obsługiwane przez tę instancję. | Ustal limit globalny albo osobne pule dla klientów. |
| Wiele instancji i licznik lokalny na każdej z nich | Każda instancja może dopuścić ruch niezależnie, więc łączny limit będzie wyższy od założonego. | Sprawdź, czy limit ma być wspólny i dobierz mechanizm, który go współdzieli. |
| Wspólny adres IP wielu użytkowników | Limit oparty wyłącznie na IP może objąć kilka osób naraz. | Jeśli użytkownik jest uwierzytelniony, rozważ partycję po jego identyfikatorze. |
Limity wygładzają ruch, lecz same nie zastępują uwierzytelniania ani ochrony przed nadużyciami. Przy wdrożeniu w Azure lub innym środowisku wieloinstancyjnym sprawdź, gdzie faktycznie działa licznik i czy żądania nie trafiają do kilku niezależnych pul.
Dobry kontrakt rozstrzyga, co zrobić po niepewnej odpowiedzi
API jest przewidywalne wtedy, gdy klient zna nie tylko poprawną ścieżkę, ale także zachowanie przy timeoutach, błędach danych i przekroczeniu limitu. Metody, statusy, format odpowiedzi i zasady ponawiania składają się na jeden kontrakt, który powinien pozostać spójny w kodzie oraz dokumentacji.
Przy projektowaniu endpointu warto najpierw ustalić, czy operacja odczytuje dane, czy zmienia stan, a potem rozstrzygnąć, jak klient rozpozna wynik po utracie połączenia. To właśnie ta decyzja może zdecydować, czy ponowne kliknięcie „Zamów” będzie nieszkodliwe, czy utworzy kolejne zamówienie.
