Основи REST та GraphQL API: відмінності й приклади використання

REST, або Representational State Transfer, — це архітектурний стиль взаємодії компонентів у розподіленій системі, найчастіше в інтернеті. REST базується на тому, що кожна взаємодія між клієнтом і сервером може бути представлена станом ресурсу.

Ресурс у REST — це будь-яка сутність, яку ти хочеш представити через API. Наприклад: користувачі, статті, товари тощо.

---

Основні принципи REST

1. Ресурси ідентифікуються URI
   Кожен ресурс у системі має унікальний URI (наприклад: /users/1, /products/42).
2. Використання стандартних HTTP-методів:
   REST API спирається на HTTP-методи:
   • GET: Отримання ресурсу.
   • POST: Створення нового ресурсу.
   • PUT: Оновлення ресурсу.
   • DELETE: Видалення ресурсу.
3. Без стану (stateless):
   Сервер не зберігає інформацію про поточний стан клієнта між запитами. Кожна взаємодія — самостійна.
4. Підтримка різних форматів даних:
   Зазвичай дані передаються у форматі JSON, але REST API може також підтримувати XML, HTML та інші формати.

Приклад простого REST API ендпоінта для отримання інформації про користувача:

GET http://example.com/users/1

Відповідь (у форматі JSON):

{
  "id": 1,
  "name": "Іван Петров",
  "email": "ivan.petrov@example.com"
}

REST став популярним не просто так — він виявився простим і зручним рішенням. Зрозумілі URL-адреси, стандартні методи типу GET і POST та хороша підтримка у веб-екосистемі зробили його природним вибором для багатьох розробників. До того ж з ним легко інтегруватися: REST добре працює з браузерами, мобільними додатками та іншими сервісами.

Але в цього підходу є й слабкі сторони. Наприклад, якщо в ресурсу сотні полів, то клієнт може отримати набагато більше даних, ніж реально потрібно. І ось тут на сцену виходить GraphQL.

---

Основи GraphQL API

GraphQL був розроблений у Facebook у 2015 році як альтернатива REST. На відміну від REST, який фокусується на ресурсах, GraphQL зосереджений на запитах (queries).

Основні концепції GraphQL

1. Запити (Query):
   Клієнт запитує тільки ті поля даних, які йому потрібні. Це рятує від зайвих даних.
2. Мутації (Mutation):
   Використовуються для створення, оновлення або видалення даних на сервері.
3. Підписки (Subscription):
   Дають змогу отримувати оновлення від сервера в реальному часі, щойно дані змінюються.

Приклад запиту GraphQL.
Давай запитаємо інформацію про користувача, але тільки його name і email:

query {
  user(id: 1) {
    name
    email
  }
}

Відповідь від сервера:

{
  "data": {
    "user": {
      "name": "Іван Петров",
      "email": "ivan.petrov@example.com"
    }
  }
}

Чому GraphQL став популярним?

• Відсутність зайвих даних: можна запитувати тільки ті дані, які потрібні.
• Гнучкість: складні запити можна описати в одному виклику.
• Автоматична документація: схема GraphQL описує всі доступні об'єкти й поля.

Втім, GraphQL може ускладнити реалізацію й вимагатиме більше зусиль для початкового налаштування.

---

Відмінності між REST і GraphQL

Приклад: отримання даних про користувача і його замовлення.
У REST для отримання цієї інформації може знадобитися кілька запитів:

1. Отримати інформацію про користувача:

   GET /users/1

2. Отримати список його замовлень:

   GET /users/1/orders

У GraphQL це все можна зробити одним запитом:

query {
  user(id: 1) {
    name
    email
    orders {
      id
      amount
      status
    }
  }
}

Відповідь:

{
  "data": {
    "user": {
      "name": "Іван Петров",
      "email": "ivan.petrov@example.com",
      "orders": [
        {
          "id": 101,
          "amount": 1500,
          "status": "completed"
        },
        {
          "id": 102,
          "amount": 500,
          "status": "pending"
        }
      ]
    }
  }
}

---

Коли використовувати REST, а коли GraphQL?

REST краще:

• Малі додатки з простою структурою даних.
• Більшість клієнтів API очікує фіксовану структуру даних (наприклад, стандартні мобільні додатки).
• Коли немає потреби в надто великій гнучкості запитів.

GraphQL краще:

• Складні додатки з різноманітними структурами даних.
• Клієнту потрібно запитувати лише певні поля (наприклад, мобільний додаток з обмеженим простором екрана або блочно-залежний інтерфейс).
• Коли потрібен один універсальний ендпоінт для всіх операцій.

Зверніть увагу: FastAPI може підтримувати і REST, і GraphQL, тому вибір завжди залежить від ваших вимог.

---

Приклад використання REST і GraphQL

Наведемо приклад REST API на FastAPI.
Припустимо, що в нашій системі є користувачі, і ми хочемо створити ендпоінт для їх отримання.

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    return {"id": user_id, "name": "Іван Петров", "email": "ivan.petrov@example.com"}

Запит:

GET http://localhost:8000/users/1

Відповідь:

{
  "id": 1,
  "name": "Іван Петров",
  "email": "ivan.petrov@example.com"
}

Приклад GraphQL API на FastAPI.
Встановимо бібліотеку для GraphQL:

pip install strawberry-graphql

Код:

from fastapi import FastAPI
from strawberry.fastapi import GraphQLRouter
import strawberry
from dataclasses import dataclass

@strawberry.type
@dataclass  
class User:
    id: int
    name: str
    email: str

@strawberry.type
class Query:
    @strawberry.field
    def user(self, id: int) -> User:
        return User(id=id, name="Іван Петров", email="ivan.petrov@example.com")

schema = strawberry.Schema(query=Query)
graphql_app = GraphQLRouter(schema)

app = FastAPI()
app.include_router(graphql_app, prefix="/graphql")

Запит:

query {
  user(id: 1) {
    name
    email
  }
}

Відповідь:

{
  "data": {
    "user": {
      "name": "Іван Петров",
      "email": "ivan.petrov@example.com"
    }
  }
}

Ми лише торкнулися поверхні, але цей приклад показує, як REST і GraphQL можуть бути реалізовані в FastAPI. У наступних лекціях ми подивимося, як комбінувати їх для створення потужних інтеграцій.