• Aplikacje webowe
  • Web API w ASP.NET Core i zasady, które chronią zamówienia

Web API w ASP.NET Core i zasady, które chronią zamówienia

Bruno Krawczyk • 18 listopada 2026
Schemat autoryzacji użytkownika przez web API. Użytkownik loguje się, otrzymuje token dostępu, a następnie wysyła żądanie do Games API.

Spis treści

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.

Schemat przepływu autoryzacji dla web API. Użytkownik prosi o autoryzację, otrzymuje token, a następnie wysyła żądanie REST API z tokenem do Games API.

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ę.

SytuacjaMożliwy skutekCo zrobić
Jedna instancja i limit dla całej aplikacjiLicznik 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 nichKaż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ówLimit 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.

FAQ - Najczęstsze pytania

Nie zakładaj, że operacja się nie udała: serwer mógł już zapisać zamówienie. Automatyczne ponowienie POST może utworzyć drugi rekord. Jeśli operacja musi używać POST, serwer może obsługiwać klucz idempotencji, zapisując go i sprawdzając przy kolejnych żądaniach.

Ponowienie GET jest zwykle bezpieczne, bo służy do odczytu. POST często inicjuje nową operację, więc jego automatyczne ponowienie może ją wykonać drugi raz. PUT i DELETE są idempotentne zgodnie z semantyką HTTP, czyli wielokrotne wykonanie ma taki sam zamierzony skutek jak pojedyncze.

Minimal APIs pasują do prostych usług z krótkimi endpointami i niewielką liczbą reguł. Kontrolery ułatwiają organizację aplikacji, gdy endpointów przybywa, a wiele z nich współdzieli walidację, filtry i strukturę klas. Żaden wariant sam nie gwarantuje dobrego kontraktu API.

Każda instancja za load balancerem może prowadzić własny licznik i niezależnie dopuszczać ruch, przez co łączny limit będzie wyższy od planowanego. Jeśli limit ma być wspólny dla usługi, trzeba dobrać mechanizm współdzielący licznik. Warto też dobrać klucz partycji do celu, na przykład identyfikator użytkownika, adres IP lub klucz API.

Oceń artykuł

Ocena: 0.00 Liczba głosów: 0

Tagi

web api
http
openapi
asp.net core
idempotencja
Autor Bruno Krawczyk
Bruno Krawczyk
Mam na imię Bruno i od 8 lat zgłębiam tajniki programowania w ekosystemie .NET, chmury Azure oraz sztucznej inteligencji. Moja przygoda z technologią zaczęła się od ciekawości, jak złożone systemy mogą ułatwiać codzienne życie i rozwiązywać realne problemy. Dziś moją misją jest dzielenie się tą wiedzą, starając się przybliżyć nawet najbardziej skomplikowane zagadnienia w sposób zrozumiały i przystępny dla każdego. W moich artykułach na kursdotnet.pl skupiam się na praktycznych aspektach, analizuję najnowsze trendy i weryfikuję informacje, aby dostarczyć Wam treści, które są nie tylko dokładne i aktualne, ale przede wszystkim użyteczne w Waszej własnej ścieżce rozwoju technologicznego.

Udostępnij artykuł

Napisz komentarz