Как выглядит простой REST-эндпоинт для получения списка ресурсов и что должен содержать хороший ответ списка?

Короткий ответ

Эндпоинт списка должен принимать параметры фильтрации/сортировки/пагинации через query-параметры и возвращать сами элементы вместе с метаданными (общее количество или признак следующей страницы), а не только "голый" массив.

Как это работает подробнее

клиент вызывает GET /resource?..., сервер применяет фильтры к запросу к БД, ограничивает выборку пагинацией и формирует структурированный ответ. Возврат "голого" массива усложняет добавление метаданных в будущем без breaking change (так как корневой элемент JSON уже занят массивом).

Пример кода

example.pyКопировать

from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/articles")
def list_articles(
    author: str | None = Query(default=None),
    page: int = Query(default=1, ge=1),
    per_page: int = Query(default=20, ge=1, le=100),
):
    query = build_query(author=author)
    total = count_articles(query)
    items = fetch_articles(query, page=page, per_page=per_page)
    return {
        "items": items,
        "page": page,
        "per_page": per_page,
        "total": total,
    }

Что использовать на практике

• Рекомендация. оборачивание списка в объект ({"items": [...], "total": N, "page": P}) с самого начала облегчает последующее добавление полей без изменения структуры верхнего уровня — это пример продуманного контракта на будущее.

Подводные камни

• Риски. возвращать просто [...] на верхнем уровне ответа, из-за чего позже невозможно добавить метаданные без нарушения совместимости для всех текущих клиентов; не документировать, какие query-параметры поддерживаются и какие у них значения по умолчанию.