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

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
- 01Czym jest FastAPI i do czego służy na starcie backendu?
- 02Jak postawić pierwsze API lokalnie — środowisko, endpoint, odpowiedź JSON?
- 03Jak dodać prosty model i walidację wejścia?
- 04Skąd biorą się automatyczne docs (OpenAPI) i jak z nich korzystać?
- 05Kiedy FastAPI, a kiedy Django lub Flask?
- 06Jak włożyć małe API do portfolio juniora?
- 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.
- Utwórz katalog projektu i wirtualne środowisko Pythona, a następnie aktywuj je.
- Zainstaluj FastAPI oraz serwer uruchomieniowy i zapisz zależności w pliku requirements.txt.
- Utwórz plik main.py z aplikacją i jednym endpointem zwracającym JSON.
- Uruchom serwer w trybie deweloperskim i sprawdź odpowiedź w przeglądarce.
- Dodaj model danych z walidacją i endpoint przyjmujący takie dane metodą POST.
- Otwórz automatyczną dokumentację, wypróbuj endpointy i sprawdź odpowiedzi na błędne dane.
- 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:
python -m venv .venv
source .venv/bin/activate
pip install fastapi "uvicorn[standard]"
pip freeze > requirements.txtNa Windowsie aktywacja wygląda inaczej — komendę znajdziesz w dokumentacji Pythona. Teraz plik main.py z najprostszym endpointem:
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.
| Krok | Plik lub komenda | Efekt |
|---|---|---|
| 1. Środowisko | python -m venv .venv | osobny katalog z bibliotekami projektu |
| 2. Instalacja | pip install fastapi "uvicorn[standard]" | framework i serwer są dostępne w projekcie |
| 3. Aplikacja | main.py | jeden endpoint zwraca JSON |
| 4. Uruchomienie | uvicorn main:app --reload | API działa lokalnie i odświeża się po zmianach |
| 5. Model i walidacja | klasa modelu w main.py | błędne dane są odrzucane z czytelnym komunikatem |
| 6. Dokumentacja | automatyczna strona docs | każdy endpoint można wypróbować w przeglądarce |
| 7. README i Git | README.md, git init | projekt 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.
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 zadaniaCo 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 programSką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.
| Sytuacja | Naturalny wybór | Dlaczego |
|---|---|---|
| Budujesz samo API dla frontendu lub aplikacji mobilnej | FastAPI | walidacja i dokumentacja są w standardzie |
| Potrzebujesz pełnej aplikacji z użytkownikami, bazą i panelem | Django | wiele elementów jest gotowych |
| Chcesz bardzo mały serwis lub prototyp | Flask lub FastAPI | niewiele konfiguracji na start |
| Uczysz się, jak działa HTTP i API | FastAPI | wynik 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


