Создание первого простого API (GET-запрос)

Сегодня мы научимся создавать простой API с использованием HTTP-метода GET, который является основным способом получения данных от сервера. Мы разберем ключевые концепции, такие как эндпоинты, обработка запросов и возврат данных в формате JSON.

---

Создание эндпоинтов

Эндпоинт — это конкретный путь (URL), по которому ваше приложение отвечает на запросы. В мире веб-разработки эндпоинт — это аналог двери, за которой кто-то (сервер) ждет, чтобы ответить на ваш запрос. В FastAPI создание эндпоинтов — дело пары строк кода.

Вот минимальный пример приложения с одним эндпоинтом, который отвечает на запрос по адресу /:

# main.py
from fastapi import FastAPI
# Создаем экземпляр приложения
app = FastAPI()
# Создаем эндпоинт
@app.get("/")
async def read_root():
    return {"message": "Привет, мир!"}

Что здесь происходит:

• Мы создали экземпляр приложения FastAPI, назвав его app.
• Использовали декоратор @app.get("/") для указания, что функция read_root должна обрабатывать GET-запросы на корневой URL /.
• Функция возвращает JSON-ответ: {"message": "Привет, мир!"}.

Запуск приложения

1. Сохраните код в файле main.py.
2. В терминале выполните команду:

   uvicorn main:app --reload

3. Откройте браузер и перейдите по адресу http://127.0.0.1:8000. Если вы увидели текст {"message":"Привет, мир!"}, поздравляю, вы только что создали свой первый API!

---

Работа с HTTP-методами

FastAPI поддерживает все основные HTTP-методы, такие как GET, POST, PUT, DELETE. Сегодня мы сосредоточимся на методе GET.

GET-запрос используется для получения данных с сервера. Он работает аналогично тому, как вы спрашиваете друга: "Какие у тебя планы на вечер?" Ваш друг возвращает вам ответ (например, "Пойду смотреть FastAPI-туториал"), и вы довольны. Так и сервер возвращает данные, которые вы запрашиваете.

Пример GET-запроса:

@app.get("/items/")
async def get_items():
    return {"items": ["яблоко", "апельсин", "банан"]}

Если вы зайдете по адресу http://127.0.0.1:8000/items/, результатом будет JSON:

{"items": ["яблоко", "апельсин", "банан"]}

---

Параметры для эндпоинтов (введение)

Иногда нам нужно получить данные не просто по фиксированному адресу, а, например, с учетом переданного параметра. Как это сделать? В FastAPI это очень просто.

Допустим, у нас есть магазин, и мы хотим получать данные о конкретном товаре по его ID. Код будет выглядеть так:

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

Теперь, зайдя на http://127.0.0.1:8000/items/42, вы получите результат:

{"item_id": 42}

Что здесь происходит?

• {item_id} в маршруте URL говорит FastAPI: "Ожидай, что здесь будет значение, и передай его в функцию обработчика".
• В функции указано, что параметр item_id должен быть целым числом (int). FastAPI автоматически проверит это. Например, если вы попробуете перейти по адресу /items/foo, то получите ошибку.

Пример использования Query Parameters

А что если нам нужно передать дополнительные данные? Например, задать лимит количества товаров. Для этого можно использовать Query Parameters.

@app.get("/items/")
async def read_items(limit: int = 10):
    return {"items": ["яблоко", "апельсин", "банан"][:limit]}

Теперь, если вы перейдете на http://127.0.0.1:8000/items/?limit=2, ответом будет:

{"items": ["яблоко", "апельсин"]}

---

Возврат данных в формате JSON

FastAPI возвращает данные в формате JSON по умолчанию. Это делает взаимодействие с фронтендом и клиентами (мобильные приложения, другие серверы) очень удобным.

Вы можете возвращать любые данные, которые можно преобразовать в JSON: словари, списки, строки, числа.

Пример возврата коллекции данных

@app.get("/products/")
async def get_products():
    return [
        {"id": 1, "name": "Ноутбук", "price": 75000},
        {"id": 2, "name": "Смартфон", "price": 30000},
        {"id": 3, "name": "Наушники", "price": 5000},
    ]

Запрос на http://127.0.0.1:8000/products/ вернет массив объектов:

[
    {"id": 1, "name": "Ноутбук", "price": 75000},
    {"id": 2, "name": "Смартфон", "price": 30000},
    {"id": 3, "name": "Наушники", "price": 5000}
]

---

Зачем это нужно?

Создание GET-запросов — это основа вашей работы с API. Представьте любую ситуацию, где нужно "запросить" данные: показать товары в интернет-магазине, список пользователей, прогноз погоды или даже мемы. Всё это — GET-запросы. Чем лучше вы умеете с ними работать, тем ближе вы к созданию современных приложений.

---

Полное минимальное приложение

Проработаем пример API для магазина, где можно получить информацию о товарах по их ID или посмотреть все товары.

from fastapi import FastAPI
app = FastAPI()
# Данные магазина
products = [
    {"id": 1, "name": "Ноутбук", "price": 75000},
    {"id": 2, "name": "Смартфон", "price": 30000},
    {"id": 3, "name": "Наушники", "price": 5000},
]

@app.get("/products/")
async def get_all_products():
    return products

@app.get("/products/{product_id}")
async def get_product_by_id(product_id: int):
    for product in products:
        if product["id"] == product_id:
            return product
    return {"error": "Товар не найден"}

---

Лучшие практики и типичные ошибки

При создании GET-запросов важно помнить:

1. Не возвращайте слишком много данных — это замедлит работу API.
2. Используйте параметры пути и Query Parameters для кастомизации запросов, но не путайте их.
3. Убедитесь, что поддержка асинхронности (async def) настроена, иначе вы теряете преимущество FastAPI.