Створення першого простого 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.