Skip to content

Глава 3.2: Создание первого API endpoint

Время изучения: 30 минут

1. Endpoint: Стыковочный порт для данных

Представьте, что наш API — это космическая станция. Endpoint (конечная точка) — это конкретный стыковочный порт, предназначенный для определенного типа кораблей.

  • Порт №1 — для грузовых кораблей (данные о планетах).
  • Порт №2 — для исследовательских зондов (данные о миссиях).
  • Порт №3 — для пассажирских шаттлов (данные об астронавтах).

Каждый endpoint — это уникальный URL, который отвечает за конкретную операцию с конкретным ресурсом.

💡 Космическая аналогия: GET /spaceships — это команда "ЦУП → Станции: Доложите список всех пристыкованных кораблей". Этот endpoint возвращает коллекцию ресурсов.

2. Создание "космического флота"

Пока у нас нет базы данных, создадим "симуляцию" — простой список космических аппаратов в виде словаря Python.

Откройте main.py и добавьте этот код перед определением app: 

# main.py

# Шаг 1: Создаем симуляцию базы данных
db_spaceships = {
    1: {
        "name": "Voyager-1",
        "type": "Зонд",
        "launch_year": 1977,
        "status": "Активен"
    },
    2: {
        "name": "Hubble Space Telescope",
        "type": "Телескоп",
        "launch_year": 1990,
        "status": "Активен"
    },
    3: {
        "name": "ISS",
        "type": "Станция",
        "launch_year": 1998,
        "status": "На орбите"
    }
}

# ... здесь код app = FastAPI()
Это наш "реестр космических аппаратов", с которым мы будем работать.

3. Первый endpoint: Список кораблей

Теперь создадим endpoint, который будет возвращать весь наш флот.

Добавьте этот код в main.py после @app.get("/"): 

# main.py

# ... код с db_spaceships, FastAPI, app и read_root() ...

@app.get("/spaceships")
def get_spaceships():
    """
    Возвращает список всех космических аппаратов в реестре.
    """
    return db_spaceships

  • @app.get("/spaceships"): Мы создали новый маршрут. Теперь GET-запросы на URL /spaceships будут обрабатываться функцией get_spaceships.
  • return db_spaceships: FastAPI автоматически преобразует словарь Python в корректный JSON-ответ.

4. Проверка работы нового стыковочного порта

Если ваш сервер uvicorn все еще запущен с флагом --reload, он уже перезагрузился и готов к работе. Если нет — запустите его снова: 

uvicorn main:app --reload

Шаг 1: Проверка в браузере

Откройте в браузере адрес http://127.0.0.1:8000/spaceships. Вы должны увидеть полный список ваших кораблей в формате JSON: 

{
  "1": {
    "name": "Voyager-1",
    "type": "Зонд",
    "launch_year": 1977,
    "status": "Активен"
  },
  "2": {
    "name": "Hubble Space Telescope",
    "type": "Телескоп",
    "launch_year": 1990,
    "status": "Активен"
  },
  "3": {
    "name": "ISS",
    "type": "Станция",
    "launch_year": 1998,
    "status": "На орбите"
  }
}

Шаг 2: Проверка в авто-документации

Перейдите на http://127.0.0.1:8000/docs. Вы увидите, что в документации появился новый раздел для эндпоинта GET /spaceships. Вы можете нажать "Try it out" и "Execute", чтобы протестировать его прямо оттуда!

5. Endpoint с параметром: Данные о конкретном корабле

Что, если нам нужны данные только о "Вояджере-1"? Для этого создадим endpoint с параметром пути (path parameter).

Добавьте этот код в main.py: 

# main.py

# ... остальной код ...

@app.get("/spaceships/{ship_id}")
def get_spaceship(ship_id: int):
    """
    Возвращает данные о конкретном космическом аппарате по его ID.
    """
    return db_spaceships.get(ship_id)

  • "/spaceships/{ship_id}": Фигурные скобки {} говорят FastAPI, что ship_id — это переменная, которая будет передана из URL.
  • ship_id: int: Это подсказка типа (type hint). FastAPI автоматически проверит, что переданный ID — это целое число. Если кто-то запросит /spaceships/voyager, FastAPI вернет ошибку валидации 422 Unprocessable Entity. Это магия!

Проверка:

Откройте http://127.0.0.1:8000/spaceships/2. Вы должны получить данные только о телескопе "Хаббл". А если откроете http://127.0.0.1:8000/spaceships/99 — получите null, так как такого корабля нет.

Квиз для закрепления

1. Endpoint в API — это...

2. Декоратор `@app.get("/users")` делает что?

3. Что означает запись `"/items/{item_id}"` в пути?

4. Зачем нужна подсказка типа `ship_id: int` в функции?

5. Если вы запросите `/spaceships/abc`, а FastAPI ожидает `int`, что произойдет?

🚀 Итог главы:

Вы успешно создали два "стыковочных порта" на вашей космической станции API:

  • 🛰️ Один для получения списка всех кораблей (/spaceships)
  • 🔭 Второй для получения данных о конкретном аппарате (/spaceships/{ship_id})

Вы также увидели мощь автоматической валидации типов FastAPI, которая защищает ваше API от некорректных запросов.

Навигационная система настроена! В следующей главе мы создадим "чертежи" наших космических кораблей с помощью Pydantic, чтобы сделать наше API еще умнее и надежнее.

📌 Проверка:

  • Сервер uvicorn запущен и работает.
  • URL http://127.0.0.1:8000/spaceships возвращает JSON со списком кораблей.
  • URL http://127.0.0.1:8000/spaceships/1 возвращает данные о "Вояджере-1".
  • URL http://127.0.0.1:8000/docs показывает два новых эндпоинта.

⚠️ Если ошибки:

  • 404 Not Found: Проверьте, правильно ли написан URL в браузере и в декораторе @app.get(...).
  • Ошибка в коде: Внимательно проверьте синтаксис, особенно отступы в Python и запятые в словаре.