Створення простого GraphQL API

Давайте створимо простий API для роботи з моделлю "Книга".
Ми реалізуємо базовий запит для отримання списку книг, а також додамо можливість додавати нові записи за допомогою мутацій.

Створення схеми (schema) в GraphQL

Схема в GraphQL — це путівник, який описує, які дані доступні для запиту і які операції можна виконувати. Вона складається з типів даних, запитів Query та мутацій Mutation. У термінології Django це можна порівняти з маршрутизацією urls.py, де ми оголошуємо шляхи та відповідні їм функції.

Додавання схеми в проєкт

1. Створюємо модель для книги

Спочатку нам потрібна базова модель для нашого API. Додамо її в наш додаток books.

# books/models.py

from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=200)  # Назва книги
    author = models.CharField(max_length=100)  # Автор книги
    published_date = models.DateField()  # Дата публікації
    price = models.DecimalField(max_digits=6, decimal_places=2)  # Ціна

    def __str__(self):
        return self.title

І не забуваємо застосувати міграції:

python manage.py makemigrations
python manage.py migrate

2. Додаємо серіалізацію моделі через DjangoObjectType

Тепер ми зв’яжемо нашу модель з GraphQL, щоб дані можна було надавати через API.

# books/schema.py

import graphene
from graphene_django.types import DjangoObjectType
from .models import Book

class BookType(DjangoObjectType):
    class Meta:
        model = Book  # Призначаємо модель, яку потрібно серіалізувати
        fields = "__all__"  # Усі поля будуть доступні для запитів

3. Створюємо схему Query

Як базова точка входу для всіх запитів, Query дозволяє визначати, які дані ми можемо отримати з API. Додамо запит, який повертає список усіх книг.

# books/schema.py (додаємо до раніше написаного)

class Query(graphene.ObjectType):
    all_books = graphene.List(BookType)  # Визначаємо тип результату: список об'єктів BookType

    def resolve_all_books(root, info):
        # Запит даних з бази
        return Book.objects.all()

4. Підключаємо схему до проєкту

Ми визначили схему для книги, але Django поки не знає, як її використовувати. Підключимо нашу схему через кореневу інтеграцію.

# books/schema.py (додаємо остаточно)

schema = graphene.Schema(query=Query)

І тепер зареєструємо цей файл у urls.py проєкту.

# myproject/urls.py

from django.urls import path
from graphene_django.views import GraphQLView

urlpatterns = [
    path('graphql', GraphQLView.as_view(graphiql=True)),  # Включаємо GraphQL та GraphiQL
]

2. Визначення точок входу в API

Давайте створимо мутацію для додавання книги.

Запити (Query) чудово підходять для читання даних, але як щодо їх зміни? Тут на допомогу приходять мутації (Mutation). Зараз ми додамо можливість створювати нову книгу через GraphQL.

# books/schema.py

class CreateBook(graphene.Mutation):
    class Arguments:
        # Аргументи, які приймає мутація
        title = graphene.String(required=True)
        author = graphene.String(required=True)
        published_date = graphene.Date(required=True)
        price = graphene.Float(required=True)

    # Визначаємо, що повертає мутація
    book = graphene.Field(BookType)

    def mutate(self, info, title, author, published_date, price):
        # Створюємо об'єкт книги
        book = Book.objects.create(
            title=title,
            author=author,
            published_date=published_date,
            price=price
        )
        return CreateBook(book=book)

Додаємо цю мутацію в кореневу схему:

# books/schema.py

class Mutation(graphene.ObjectType):
    create_book = CreateBook.Field()  # Додаємо нашу мутацію

schema = graphene.Schema(query=Query, mutation=Mutation)  # Вказуємо обидві операції

Тестування GraphQL API

Все готово! Тепер давай протестуємо наш GraphQL API через GraphiQL.

1. Запит списку книг

Відкриваємо http://127.0.0.1:8000/graphql у браузері й вводимо наступний запит:

query {
  allBooks {
    id
    title
    author
    publishedDate
    price
  }
}

Якщо ти додаси хоча б один запис у базу даних, то побачиш результат у красивому JSON-форматі.

2. Створення нової книги

Для додавання нової книги використовуємо мутацію:

mutation {
  createBook(
    title: "1984"
    author: "George Orwell"
    publishedDate: "1949-06-08"
    price: 19.99
  ) {
    book {
      id
      title
      author
    }
  }
}

Результат підтвердить успішне створення об'єкта книги:

{
  "data": {
    "createBook": {
      "book": {
        "id": "1",
        "title": "1984",
        "author": "George Orwell"
      }
    }
  }
}

Висновок

У цій лекції ми навчились створювати просту схему GraphQL, визначати запити та мутації, а також тестувати API через GraphiQL. Це перший крок до побудови більш складного та функціонального API, який ми будемо розвивати у наступних лекціях.