📚 Books GraphQL API

API GraphQL para gestión de libros construida con Django, Graphene y GraphQL. Proporciona operaciones de consulta y mutación para manejar un catálogo de libros.

📋 Tabla de Contenidos

• Descripción
• Características
• Tecnologías
• Arquitectura
• Requisitos Previos
• Instalación
• Configuración
• Ejecución
• API GraphQL
  • Queries
  • Mutations
• Estructura del Proyecto
• Modelo de Datos
• GraphQL Playground
• Ejemplos de Uso
• Pruebas
• Contribución
• Licencia

📝 Descripción

Este proyecto implementa una API GraphQL completa para la gestión de un catálogo de libros. Utiliza Django como framework backend y Graphene para crear un esquema GraphQL con queries y mutations, similar a cómo Django REST Framework permite crear APIs REST.

✨ Características

• ✅ Consulta de todos los libros
• ✅ Consulta de libro por ID
• ✅ Creación de nuevos libros mediante mutations
• ✅ Interfaz GraphQL Playground para pruebas interactivas
• ✅ Modelo de datos con timestamps automáticos
• ✅ Panel de administración Django para gestión de datos
• ✅ Validación automática de tipos

🛠️ Tecnologías

• Backend Framework: Django 4.x
• GraphQL: Graphene-Django
• Base de datos: SQLite (desarrollo) / PostgreSQL (producción)
• Python: 3.8+

🏗️ Arquitectura

┌─────────────────────────────────────────────────────────┐
│                      Django Admin                         │
│                    /admin/                                │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                   GraphQL Endpoint                        │
│                    /graphql/                              │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                    Graphene Schema                        │
│                                                           │
│  ┌──────────────┐          ┌────────────────────────┐   │
│  │    Query     │          │       Mutation         │   │
│  │              │          │                        │   │
│  │ • hello      │          │ • createBook          │   │
│  │ • books      │          │                        │   │
│  │ • book(id)   │          │                        │   │
│  └──────────────┘          └────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────────┐
│                   Django Models                          │
│                    Book                                   │
│                    • title                                │
│                    • description                          │
│                    • created_at                           │
│                    • updated_at                           │
└─────────────────────────────────────────────────────────┘

📋 Requisitos Previos

• Python 3.8 o superior
• pip (gestor de paquetes de Python)
• virtualenv (opcional pero recomendado)
• Git (opcional)

🚀 Instalación

1. Clonar el repositorio

git clone <url-del-repositorio>
cd books-graphql-api

2. Crear y activar entorno virtual

python -m venv venv
source venv/bin/activate  # Linux/Mac
# o
venv\Scripts\activate  # Windows

3. Instalar dependencias

pip install django graphene-django

4. Crear archivo requirements.txt (opcional para producción)

pip freeze > requirements.txt

⚙️ Configuración

1. Configurar el proyecto Django (si no está ya configurado):

django-admin startproject core .
python manage.py startapp books

2. Agregar aplicaciones a settings.py:

# core/settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'graphene_django',  # Agregar Graphene
    'books',            # Agregar la app de libros
]

# Configuración de GraphQL
GRAPHENE = {
    'SCHEMA': 'core.schema.schema'  # Ruta al esquema
}

3. Realizar migraciones:

python manage.py makemigrations
python manage.py migrate

4. Crear superusuario para el admin:

python manage.py createsuperuser

🎯 Ejecución

Desarrollo

python manage.py runserver

El servidor se iniciará en http://localhost:8000

Acceso a interfaces:

• GraphQL Playground: http://localhost:8000/graphql/
• Django Admin: http://localhost:8000/admin/

📚 API GraphQL

Queries

Obtener todos los libros

query {
  books {
    id
    title
    description
  }
}

Obtener un libro por ID

query {
  book(id: "1") {
    id
    title
    description
  }
}

Query de ejemplo con campo hello

query {
  hello
  books {
    id
    title
  }
}

Mutations

Crear un nuevo libro

mutation {
  createBook(title: "El Principito", description: "Un clásico de la literatura") {
    book {
      id
      title
      description
    }
  }
}

📁 Estructura del Proyecto

books-graphql-api/
├── core/
│   ├── __init__.py
│   ├── settings.py           # Configuración de Django
│   ├── urls.py               # URLs principales
│   ├── wsgi.py               
│   ├── asgi.py
│   ├── schema.py             # Esquema GraphQL principal
│   └── __pycache__/
├── books/
│   ├── __init__.py
│   ├── admin.py              # Configuración del admin
│   ├── apps.py
│   ├── models.py             # Modelo Book
│   ├── tests.py              # Pruebas
│   ├── views.py
│   ├── migrations/           # Migraciones de base de datos
│   │   └── __init__.py
│   └── __pycache__/
├── manage.py                  # Script de gestión Django
├── db.sqlite3                 # Base de datos SQLite
└── README.md                  # Este archivo

💾 Modelo de Datos

Book

class Book(models.Model):
    title = models.CharField(max_length=255)           # Título del libro
    description = models.TextField()                    # Descripción del libro
    created_at = models.DateTimeField(auto_now_add=True) # Fecha de creación
    updated_at = models.DateTimeField(auto_now=True)     # Fecha de actualización
    
    def __str__(self):
        return self.title

🔍 GraphQL Playground

El proyecto incluye GraphQL Playground (GraphiQL) en el endpoint /graphql/, proporcionando:

• Documentación automática del esquema
• Autocompletado de queries
• Historial de consultas
• Explorador de esquemas

Acceso:

1. Iniciar el servidor: python manage.py runserver
2. Navegar a: http://localhost:8000/graphql/
3. ¡Comenzar a hacer consultas!

💡 Ejemplos de Uso

Ejemplo 1: Consulta combinada

query {
  hello
  books {
    id
    title
    description
  }
}

Respuesta:

{
  "data": {
    "hello": "Hello",
    "books": [
      {
        "id": "1",
        "title": "El Principito",
        "description": "Un clásico de la literatura"
      }
    ]
  }
}

Ejemplo 2: Crear libro y consultar todos

mutation {
  createBook(title: "Cien años de soledad", description: "Gabriel García Márquez") {
    book {
      id
      title
      description
    }
  }
}

query {
  books {
    id
    title
    description
  }
}

Ejemplo 3: Consulta con variables

query GetBook($id: ID!) {
  book(id: $id) {
    title
    description
  }
}

Variables:

{
  "id": "1"
}

🧪 Pruebas

Ejecutar pruebas unitarias

python manage.py test books

Pruebas específicas

python manage.py test books.tests.BookTestCase

Ejemplo de prueba (books/tests.py)

from django.test import TestCase
from books.models import Book

class BookModelTest(TestCase):
    def setUp(self):
        Book.objects.create(title="Test Book", description="Test Description")
    
    def test_book_creation(self):
        book = Book.objects.get(title="Test Book")
        self.assertEqual(book.description, "Test Description")

📖 Documentación del Esquema GraphQL

Tipos

BookType

• id: ID!
• title: String!
• description: String!

Query

• hello: String - Retorna un saludo
• books: [BookType] - Retorna todos los libros
• book(id: ID!): BookType - Retorna un libro específico por ID

Mutation

• createBook(title: String!, description: String!): CreateBookMutation - Crea un nuevo libro

🤝 Contribución

1. Fork el proyecto
2. Crear rama feature (git checkout -b feature/AmazingFeature)
3. Commit cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abrir Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

---

✨ Mejoras Futuras

• Agregar mutations para actualizar y eliminar libros
• Implementar autenticación y permisos
• Añadir paginación en consultas de libros
• Implementar filtros avanzados (por título, fecha, etc.)
• Agregar relaciones con autores y categorías
• Implementar pruebas de integración GraphQL
• Añadir documentación con ejemplos avanzados
• Configurar CORS para producción
• Implementar rate limiting
• Agregar caché para consultas frecuentes

---

Desarrollado con ❤️ usando Django + Graphene