Основы 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.
Давайте запросим информацию о пользователе, но только его имя и 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. В следующих лекциях мы посмотрим, как комбинировать их для создания мощных интеграций.