Python

FastAPI od podstaw — pierwsze API w Pythonie krok po kroku

FastAPI od podstaw: jak uruchomić pierwszy endpoint, dodać model z walidacją, skorzystać z dokumentacji OpenAPI i przygotować małe API do portfolio.

Zespół LearnIT

8 minutZaktualizowano:
FastAPI od podstaw — pierwsze API w Pythonie krok po kroku

Krótka odpowiedź

FastAPI to framework Pythona do budowy API, który na podstawie adnotacji typów sam waliduje dane i generuje dokumentację OpenAPI. Pierwsze API postawisz lokalnie w kilku krokach: wirtualne środowisko, instalacja, plik z jednym endpointem zwracającym JSON, model z walidacją i uruchomienie serwera. Wynik od razu sprawdzisz w przeglądarce, w automatycznych docs.

Spis treści · 7
  1. 01Czym jest FastAPI i do czego służy na starcie backendu?
  2. 02Jak postawić pierwsze API lokalnie — środowisko, endpoint, odpowiedź JSON?
  3. 03Jak dodać prosty model i walidację wejścia?
  4. 04Skąd biorą się automatyczne docs (OpenAPI) i jak z nich korzystać?
  5. 05Kiedy FastAPI, a kiedy Django lub Flask?
  6. 06Jak włożyć małe API do portfolio juniora?
  7. 07Jakie błędy popełniają początkujący?

FastAPI to framework Pythona do budowy API, który na podstawie adnotacji typów sam sprawdza poprawność danych i generuje dokumentację w standardzie OpenAPI. Pierwsze API uruchomisz lokalnie w kilku krokach: wirtualne środowisko, instalacja, plik z jednym endpointem i serwer. Poniżej przechodzimy całą drogę — od pustego katalogu do małego projektu, który możesz pokazać w portfolio.

Zakładamy, że znasz podstawy Pythona: funkcje, słowniki, klasy i moduły. Jeśli dopiero zaczynasz, zacznij od nauki Pythona od podstaw, a do FastAPI wróć, gdy bez problemu piszesz własne funkcje.

Czym jest FastAPI i do czego służy na starcie backendu?

API to „drzwi” do Twojej aplikacji dla innych programów: aplikacji mobilnej, strony internetowej czy innego serwisu. Program wysyła żądanie (na przykład „daj listę zadań”), a API odpowiada, zwykle w formacie JSON. FastAPI pozwala takie drzwi zbudować szybko i bez dużej ilości kodu pomocniczego.

Co wyróżnia to podejście na początku nauki:

  • Adnotacje typów robią robotę — piszesz, że pole jest liczbą lub tekstem, a framework sprawdza dane i zwraca zrozumiały błąd, gdy ktoś wyśle coś innego.
  • Dokumentacja powstaje sama — z Twojego kodu framework buduje stronę, na której można od razu wypróbować każdy endpoint.
  • Mało kodu do pierwszego wyniku — działający endpoint to kilka linijek.
  • Dobra nauka dobrych nawyków — rozdzielasz dane wejściowe, logikę i odpowiedź, a typy zmuszają do precyzji.

FastAPI nie jest „lepsze od wszystkiego”. To narzędzie szczególnie dobre do API; jeśli budujesz pełną aplikację z panelem administracyjnym, użytkownikami i bazą, inne frameworki oferują więcej gotowych elementów. Do porównania wrócimy niżej.

Jak postawić pierwsze API lokalnie — środowisko, endpoint, odpowiedź JSON?

Poniżej siedem kroków. Poszczególne komendy możesz dopasować do swojego systemu; aktualny sposób instalacji i uruchamiania sprawdź w oficjalnej dokumentacji FastAPI.

  1. Utwórz katalog projektu i wirtualne środowisko Pythona, a następnie aktywuj je.
  2. Zainstaluj FastAPI oraz serwer uruchomieniowy i zapisz zależności w pliku requirements.txt.
  3. Utwórz plik main.py z aplikacją i jednym endpointem zwracającym JSON.
  4. Uruchom serwer w trybie deweloperskim i sprawdź odpowiedź w przeglądarce.
  5. Dodaj model danych z walidacją i endpoint przyjmujący takie dane metodą POST.
  6. Otwórz automatyczną dokumentację, wypróbuj endpointy i sprawdź odpowiedzi na błędne dane.
  7. Napisz README z opisem uruchomienia i przykładowymi żądaniami oraz zapisz projekt w Git.

Zacznijmy od środowiska. Wirtualne środowisko izoluje biblioteki projektu od reszty systemu, dzięki czemu nie psujesz innych projektów:

Terminal
python -m venv .venv
source .venv/bin/activate
pip install fastapi "uvicorn[standard]"
pip freeze > requirements.txt

Na Windowsie aktywacja wygląda inaczej — komendę znajdziesz w dokumentacji Pythona. Teraz plik main.py z najprostszym endpointem:

Python
from fastapi import FastAPI

app = FastAPI(title="Moje pierwsze API")


@app.get("/")
def strona_glowna():
    return {"status": "dziala", "wiadomosc": "Pierwsze API w FastAPI"}

Uruchom serwer poleceniem uvicorn main:app --reload i otwórz adres, który pokaże terminal (zwykle lokalny port 8000). W przeglądarce zobaczysz odpowiedź JSON. Opcja --reload restartuje serwer po każdej zmianie kodu — wygodna w nauce, ale przeznaczona do pracy lokalnej, nie do uruchamiania w produkcji.

KrokPlik lub komendaEfekt
1. Środowiskopython -m venv .venvosobny katalog z bibliotekami projektu
2. Instalacjapip install fastapi "uvicorn[standard]"framework i serwer są dostępne w projekcie
3. Aplikacjamain.pyjeden endpoint zwraca JSON
4. Uruchomienieuvicorn main:app --reloadAPI działa lokalnie i odświeża się po zmianach
5. Model i walidacjaklasa modelu w main.pybłędne dane są odrzucane z czytelnym komunikatem
6. Dokumentacjaautomatyczna strona docskażdy endpoint można wypróbować w przeglądarce
7. README i GitREADME.md, git initprojekt da się uruchomić i obejrzeć według opisu

Jak dodać prosty model i walidację wejścia?

Prawdziwa wartość frameworka widoczna jest dopiero przy danych wejściowych. Wyobraź sobie małą listę zadań. Opisujesz zadanie jako model, a FastAPI pilnuje, czy ktoś nie wysłał tekstu tam, gdzie powinna być liczba, albo nie pominął wymaganego pola.

Python
from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI(title="Lista zadań")

zadania: list[dict] = []


class NoweZadanie(BaseModel):
    tytul: str = Field(min_length=3, max_length=100)
    priorytet: int = Field(default=1, ge=1, le=3)


@app.post("/zadania", status_code=201)
def dodaj_zadanie(dane: NoweZadanie):
    zadanie = {"id": len(zadania) + 1, **dane.model_dump()}
    zadania.append(zadanie)
    return zadanie


@app.get("/zadania")
def lista_zadan():
    return zadania

Co tu się dzieje? Klasa NoweZadanie opisuje, jak ma wyglądać poprawne zadanie: tytuł od 3 do 100 znaków i priorytet od 1 do 3. Jeśli ktoś wyśle tytuł złożony z jednej litery albo priorytet równy 10, FastAPI odrzuci żądanie i zwróci komunikat o błędzie bez ani jednej linijki kodu sprawdzającego z Twojej strony. Kod odpowiedzi 201 informuje klienta, że zasób został utworzony.

Zwróć uwagę na ograniczenie tego przykładu: zadania trzymamy w liście w pamięci, więc znikają po restarcie serwera. To celowe uproszczenie, żeby skupić się na samym API. Naturalnym następnym krokiem jest baza danych (w kursowych projektach Pythona pojawia się w tym celu SQLAlchemy) oraz testy, które uruchamiają aplikację i sprawdzają odpowiedzi.

Samo uruchomienie serwera nie dowodzi jeszcze, że endpoint działa poprawnie. Po każdej zmianie sprawdź trzy rzeczy: czy odpowiedź ma oczekiwany kod, czy struktura JSON zgadza się z tym, co zapisałeś w README, oraz czy serwer w terminalu nie pokazuje ostrzeżeń. Dobrze jest robić to za każdym razem w tej samej kolejności, bo wtedy szybciej zauważysz, który krok się zmienił. Zacznij od prostego żądania na głównym adresie, potem dodaj zadanie, a na końcu pobierz listę i upewnij się, że nowy wpis się na niej pojawił.

Równie ważne jest sprawdzenie ścieżki błędnej. Wyślij zadanie bez tytułu, z za krótkim tytułem i z priorytetem spoza zakresu, a następnie przeczytaj odpowiedź. FastAPI zwraca kod 422 oraz listę problemów wskazującą, które pole i dlaczego zostało odrzucone. Ten komunikat jest też pierwszym miejscem, w którym warto szukać przyczyny, gdy aplikacja kliencka nie może zapisać danych. Pamiętaj, że walidacja chroni tylko to, co opisałeś w modelu — reguły biznesowe, takie jak zakaz duplikatów, musisz dopisać samodzielnie i również je przetestować.

Kiedy ręczne klikanie zaczyna się powtarzać, zamień je w automatyczne testy. Biblioteka pytest wraz z klientem testowym dostarczanym przez FastAPI (doinstaluj pytest i httpx, którego ten klient wymaga) pozwala wywołać endpointy bez uruchamiania serwera i porównać kod oraz treść odpowiedzi z oczekiwaniem. Wystarczą dwa lub trzy testy: poprawne dodanie zadania, odrzucenie błędnych danych i odczyt listy. Taki zestaw jest krótki, a w portfolio pokazuje, że potrafisz sprawdzić własny kod, nie tylko go napisać. Wspomnij o nim w README razem z poleceniem, które go uruchamia.

Wolisz uczyć się w ustalonej kolejności?

Sprawdź kurs Python Developer w LearnIT — program, projekty i feedback do kodu.

Zobacz program

Skąd biorą się automatyczne docs (OpenAPI) i jak z nich korzystać?

OpenAPI to standard opisu API: lista ścieżek, metod, parametrów i formatów odpowiedzi. FastAPI buduje taki opis z Twojego kodu — z dekoratorów ścieżek, adnotacji typów i modeli — i udostępnia go jako interaktywną stronę. Zwykle znajdziesz ją pod adresem /docs uruchomionej aplikacji. Opis w formacie JSON, z którego korzystają inne narzędzia, jest dostępny osobno.

Jak z tego korzystać w praktyce:

  • Testuj bez dodatkowych narzędzi — na stronie możesz wysłać żądanie do każdego endpointu i zobaczyć odpowiedź.
  • Sprawdzaj walidację — wyślij celowo błędne dane i przeczytaj komunikat; to szybkie sprawdzenie, czy model robi to, co zamierzałeś.
  • Opisuj endpointy — dodaj krótkie opisy i przykładowe wartości, bo dokumentacja jest dobra tak, jak Twoje nazwy i opisy.
  • Pokaż ją w portfolio — zrzut ekranu albo opis w README od razu pokazuje, co API potrafi.

Pamiętaj, że automatyczna dokumentacja nie zastępuje README. Mówi, co API robi, ale nie mówi, jak je uruchomić, do czego służy i jakie ma ograniczenia.

Kiedy FastAPI, a kiedy Django lub Flask?

Pełne porównanie znajdziesz w artykule Django, Flask czy FastAPI; tutaj tylko skrót, który pomoże wybrać pierwszy projekt.

SytuacjaNaturalny wybórDlaczego
Budujesz samo API dla frontendu lub aplikacji mobilnejFastAPIwalidacja i dokumentacja są w standardzie
Potrzebujesz pełnej aplikacji z użytkownikami, bazą i panelemDjangowiele elementów jest gotowych
Chcesz bardzo mały serwis lub prototypFlask lub FastAPIniewiele konfiguracji na start
Uczysz się, jak działa HTTP i APIFastAPIwynik widać od razu, w dokumentacji

Nie musisz wybierać „na całe życie”. Pojęcia — ścieżka, metoda, kod odpowiedzi, walidacja — przenoszą się między frameworkami. Wybierz jeden i zrób w nim domknięty projekt; drugiego nauczysz się szybciej. Szerszy obraz ścieżki backendowej opisuje tekst Python backend — jak zacząć.

Jak włożyć małe API do portfolio juniora?

Pomysły na projekty znajdziesz w tekście projekty Python do portfolio. Tu skupmy się na tym, co sprawia, że małe API wygląda profesjonalnie. Osoba przeglądająca Twoje repozytorium zwykle nie czyta całego kodu — sprawdza README, strukturę projektu i to, czy da się go uruchomić.

Lista kontrolna „API gotowe do pokazania”:

  • README opisuje, co robi API, jak je uruchomić i jak wywołać przykładowe endpointy.
  • Plik z zależnościami pozwala odtworzyć środowisko jednym poleceniem.
  • Endpointy mają czytelne nazwy i opisy widoczne w automatycznej dokumentacji.
  • Dane wejściowe są walidowane, a błędy zwracają zrozumiałe komunikaty.
  • Kody odpowiedzi są sensowne: 201 po utworzeniu, 404 dla brakującego zasobu, 422 dla błędnych danych.
  • Są podstawowe testy, które uruchamiają aplikację i sprawdzają odpowiedzi.
  • W repozytorium nie ma haseł, kluczy ani plików z danymi dostępowymi; konfigurację czytasz ze zmiennych środowiskowych.
  • Repozytorium ma historię commitów z czytelnymi opisami zmian.

Dobry sposób na rozwój projektu to dokładanie jednej rzeczy naraz: najpierw przechowywanie w bazie danych, potem uwierzytelnianie, potem testy, na końcu uruchomienie w kontenerze. Każdy z tych kroków można opisać w README jako osobny etap. Dzięki temu repozytorium pokazuje proces uczenia się, a nie tylko końcowy wynik.

Jakie błędy popełniają początkujący?

Pierwszy to przechowywanie danych w zmiennej w pamięci i traktowanie tego jako gotowego rozwiązania — przy restarcie wszystko znika. Drugi to brak walidacji i obsługa błędów „na zaufanie”, że klient zawsze wyśle poprawne dane. Trzeci to wpisywanie kluczy i haseł prosto w kod, który trafia do repozytorium. Czwarty to uruchamianie trybu deweloperskiego jako docelowego sposobu działania aplikacji. Piąty to przeskakiwanie między frameworkami zamiast domknięcia jednego projektu.

Chcesz nauczyć się backendu w Pythonie z prowadzącym i praktycznymi projektami? Sprawdź program kursu Python Developer — w opisie programu pojawiają się między innymi FastAPI, Django, Flask i Git. O zasadach ewentualnego wsparcia kosztów przeczytasz w opisie dofinansowania kursów IT — to informacja o zasadach, nie obietnica przyznania środków.

Chcesz nauczyć się programowania w Pythonie?

Przejdź od teorii do praktyki pod okiem mentorów. Sprawdź kurs Python Developer w LearnIT.

Zobacz kurs Python Developer

Najczęstsze pytania

To framework Pythona do tworzenia API, oparty na adnotacjach typów. Na ich podstawie waliduje dane wejściowe i automatycznie generuje dokumentację w standardzie OpenAPI.

Tak, jeśli znasz podstawy Pythona: funkcje, słowniki i klasy. Pierwszy działający endpoint zajmuje kilka linijek, a dokumentacja pozwala od razu testować wynik.

Zainstaluj FastAPI i serwer uruchomieniowy w wirtualnym środowisku, utwórz plik z aplikacją i funkcją oznaczoną dekoratorem ścieżki, a następnie uruchom serwer w trybie deweloperskim. Wynik zobaczysz w przeglądarce.

Framework buduje opis API w standardzie OpenAPI z Twoich ścieżek i modeli, a następnie udostępnia go jako interaktywną stronę. Nie piszesz jej ręcznie, ale musisz dbać o czytelne nazwy i opisy.

FastAPI jest lekkie i nastawione na API. Django daje komplet narzędzi do aplikacji z bazą, panelem i uwierzytelnianiem. Szerzej porównujemy je w artykule Django, Flask czy FastAPI.

Tak, o ile da się je uruchomić według README, ma walidację, kilka sensownych endpointów i przynajmniej podstawowe testy. Mały, domknięty projekt jest lepszy niż duży, niedokończony.

W opisie kursu Python Developer pojawiają się między innymi FastAPI, Django i Flask. Zasady ewentualnego wsparcia kosztów opisuje strona o dofinansowaniu kursów IT.

Uzyskaj bezpłatną konsultację

Wypełnij formularz i otrzymaj kilka rozdziałów naszego podręcznika w prezencie!

Phone
form