Search for a command to run...
Soy Carlos Alberto Alegre, analista programador y desarrollador web front-end y back-end. Me considero un autodidacta entusiasta y disfruto explorando y aprendiendo nuevas tecnologías para mantenerme al tanto de las últimas tendencias en diseño y desarrollo web.
No comments yet. Be the first to comment.
Guía completa para integrar y mostrar contenido de Hashnode en tu web por medio de su API publica.
Integración de ReactJS y FaunaDB: tutorial paso a paso
Aprende a integrar el sistema de almacenamiento de Supabase en tu aplicación VueJS
Guía paso a paso para integrar Cloudinary en tu aplicación VueJS y subir imágenes de forma fácil y segura
Integración GqlGen y Gorm
Graphql es un lenguaje de consultas que provee una completa descripción de los datos de tu API, permitiendo al cliente recuperar solo los datos que necesita. Esto permite resolver algunos de los problemas más comunes como por ejemplo obtener menos datos de los que la aplicación necesita (underfetching) por lo que obliga al cliente realizar una segunda consulta al servidor, o recuperar más información del requerido (overfetching) por lo que los datos superfluos se descartan.
En este tutorial vamos a crear un API Graphql en que cual integraremos Flask y Ariadne. Flask es un ligero framework para desarrollo de aplicaciones web, diseñado para comenzar rápido y fácil, por lo que se ha convertido en uno de los frameworks Python más populares. Ariadne es un framework schema-first que permite definir APIs Graphql en Python y fácil de integrar con Flask.
Este tutorial es completamente práctico, por lo que no voy a ahondar en conceptos teóricos por lo que se requiere tener algunas nociones sobre desarrollo en Python, Flask, Graphql (tipos de datos, queries, mutaciones, etc).
El proyecto consiste en un API Graphql para guardar, consultar, modificar y eliminar datos sobre autores y libros. Estableceremos una relación "one to many" de forma que un autor puede tener muchos libros, y un libro pertenece a un autor. Generaremos las queries de forma que al consultar los autores podamos acceder a los libros que tienen y, al consultar los libros poder ver los autores al que pertenecen. Las mutations nos permitirán añadir autores y libros, actualizarlos y eliminarlos.
Comencemos creando el directorio del proyecto, yo lo llamé tutorial-flask-ariadne. Dentro de esta carpeta definimos un entorno virtual, para ello abre la consola e ingresa el siguiente comando python -m venv venv. Para activar el entorno escribe venv\Scripts\activate.
Instalamos Flask y Ariadne con el siguiente comando.
pip install -U flask ariadne
Seguimos con la instalación de flask-sqlalchemy, flask-marshmallow y sqlalchemy-marshmallow.
pip install -U flask-sqlalchemy flask-marshmallow marshmallow-sqlalchemy
Para poder conectarnos con nuestra base de datos necesitamos un driver. Lo instalamos como sigue python -m pip install PyMySQL.
Finalmente instalamos python-dotenv que nos permitirá leer nuestras variables de entorno.
Abre tu gestor de base de datos y crea una para nuestra app. Yo lo llamé tutorial_flask_ariadne. En la raíz del proyecto añade un fichero .env y define las siguientes variables de entorno.
USER="root"
PASSWORD=
PORT=3306
DATABASE="tutorial_flask_ariadne"
HOST="localhost"
A continuación integramos flask con ariadne para crear un servidor graphql. En la raíz de tu proyecto añade un fichero main.py y agrega el siguiente código.
from ariadne import QueryType, graphql_sync, make_executable_schema
from ariadne.constants import PLAYGROUND_HTML
from flask import Flask, request, jsonify
type_defs = """
type Query {
hello: String!
}
"""
query = QueryType()
@query.field("hello")
def resolve_hello(_, info):
request = info.context
user_agent = request.headers.get("User-Agent", "Guest")
return "Hello, %s!" % user_agent
schema = make_executable_schema(type_defs, query)
app = Flask(__name__)
@app.route("/graphql", methods=["GET"])
def graphql_playground():
return PLAYGROUND_HTML, 200
@app.route("/graphql", methods=["POST"])
def graphql_server():
data = request.get_json()
success, result = graphql_sync(
schema,
data,
context_value=request,
debug=app.debug
)
status_code = 200 if success else 400
return jsonify(result), status_code
if __name__ == "__main__":
app.run(debug=True)
Este código lo tomamos de la documentación oficial de Ariadne. Lo que podemos destacar son los dos endpoint principales. El primero captura una petición GET que nos da acceso al playground en el cual podremos testear nuestra API Graphql. El segundo captura las peticiones POST el cual se encarga de llevar a cabo nuestras queries y mutations.
También podemos ver una variable type_defs en el cual definiremos nuestra queries , mutations, types, etc. En este caso se define una sola consulta hello que retorna un string. La función resolve_hello es la que se encarga de resolver esta Query; en este caso retorna un saludo "Hello" y la información del navegador.
Con el comando flask --app main run puedes correr el servidor de desarrollo. Ingresa al endpoint 127.0.0.1:5000/graphql para ver el playground.
A continuación seguiremos con la definición de los modelos y los esquemas de serialización.
Comencemos creando un nuevo directorio models para los modelos. Dentro de este directorio añade un fichero __init__.py. Este fichero le indica al interprete de Python que el directorio es un paquete en el cual estarán nuestros módulos. Usaremos este fichero para inicializar SQLAlchemy y Marshmallow.
from flask_sqlalchemy import SQLAlchemy
from flask_marshmallow import Marshmallow
db = SQLAlchemy()
ma = Marshmallow()
Ahora creamos los archivos author.py y book.py para los modelos autor y libro respectivamente. Definiremos el modelo author primero. Dentro de este fichero inserta el siguiente código.
from models import db
class Author (db.Model):
__tablename__= "authors"
id= db.Column(db.Integer, primary_key=True)
name= db.Column(db.String(255))
lastname= db.Column(db.String(255))
created_at= db.Column(db.DateTime, server_default=db.func.now())
updated_at= db.Column(db.DateTime, server_default=db.func.now(), onupdate=db.func.now())
books= db.relationship("Book", backref="author", cascade="all, delete-orphan")
Lo primero que podemos ver es que importamos db que es la instancia de SQLAlchamy() que definimos anteriormente. Seguimos con la declaración de la clase Author, los campos y la relación. Con la directiva __tablename__ indicamos el nombre de la tabla. Los campos id, name y lastname se explican por sí mismos. Los campos created_at y updated_at son timestamps que registran la fecha en que un registro es creado y actualizado.
La última línea define la relación. El primer parámetro indica el modelo al cual se vincula, en este caso Book. El parámetro backref agrega una referencia en el modelo Book que se comportará como la columna que le dará acceso al autor del libro. El parámetro cascade significa de que si el registro de la tabla padre (Author) es borrado, todos los registros relacionados en la tabla hija (Book) serán eliminados también.
Continuamos con el fichero book.py.
from models import db
class Book (db.Model):
__tablename__="books"
id= db.Column(db.Integer, primary_key=True)
title= db.Column(db.String(255))
created_at= db.Column(db.DateTime, server_default=db.func.now())
updated_at= db.Column(db.DateTime, server_default=db.func.now(), onupdate=db.func.now())
author_id = db.Column(db.Integer, db.ForeignKey("authors.id"))
La definición de este modelo no difiere del anterior. Tenemos un campo id, title para el título del libro y los campos para los timestamps. Lo que podemos destacar es el campo author_id que es la que usamos como llave foránea para vincular esta tabla con la tabla autor, usando su id. De esta manera queda definida la relación "one to many" entre las tablas.
Seguimos con la definición de los esquemas para serialización/deserialización.
Para mantener esto simple, definiremos los ficheros para los esquemas dentro del mismo directorio models. Crea dos archivos authorSchema.py y bookSchema.py. Primero authorSchema.py.
from models import ma
from models.author import Author
class AuthorSchema(ma.SQLAlchemyAutoSchema):
class Meta:
model = Author
include_relationships = True
books= ma.List(ma.Nested("BookSchema", exclude=("author",)))
Primero importamos la instancia de Marshmallow , ma. En la segunda línea indicamos que del módulo models.author queremos importar la clase Author. Definimos la clase AuthorSchema y le pasamos como parámetro ma.SQLAlchemyAuthorSchema. Con el atributo model vinculamos este esquema con el modelo Author. include_relationships = True indica que nos incluya las relaciones declaradas en el modelo.
La línea books= ma.List(ma.Nested("BookSchema", exclude=("author",))) indica que el atributo books es una arreglo de libros, el cual tiene un esquema anidado (BookSchema). Es importante destacar la opción exclude. En él declaramos que excluya este campo, para evitar recursión infinita.
Continuamos con el esquema para los libros. Abre el fichero bookSchema.py y añade.
from models import ma
from models.book import Book
class BookSchema(ma.SQLAlchemyAutoSchema):
class Meta:
model = Book
include_fk = True
author= ma.Nested("AuthorSchema", only=("id", "name", "lastname"))
Como puedes ver no difiere mucho del esquema anterior. Mediante el atributo model vinculamos este esquema con el modelo Book. Con include_fk indicamos que nos incluya la llave foránea.
La línea author= ma.Nested("AuthorSchema", only=("id", "name", "lastname")) indica que el atributo author tiene un esquema anidado AuthorSchema para acceder a los datos del autor. Con la opción only señalamos los campos que queremos recuperar de AuthorSchema. Al igual que la opción exclude de AuthorSchema, nos sirve para evitar recursión infinita.
Con esto finalizamos con los modelos y los esquemas. Continuamos con la conexión a la base de datos.
Para establecer la conexión primero importamos import os para interactuar con las funciones del sistema operativo. Lo utilizaremos para obtener los valores de las variables de entorno que definimos en el fichero .env.
También importamos los módulos del directorio models.
from models import db, ma
from models.author import Author
from models.book import Book
from models.authorSchema import AuthorSchema
from models.bookSchema import BookSchema
Justo después de definir app=Flask(__name__) agregamos la conexión.
app.config["SQLALCHEMY_DATABASE_URI"] = "mysql+pymysql://{}@{}:{}/{}".format(os.environ.get("USER"), os.environ.get("HOST"), os.environ.get("PORT"), os.environ.get("DATABASE"))
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
db.init_app(app)
ma.init_app(app)
with app.app_context():
db.create_all()
La opción app.config["SQLALCHEMY_DATABASE_URI"] recibe un string con los valores de USER, PORT y DATABASE.
Luego inicializamos las extensiones de SQLAlchemy y Marshmallow, en ese orden. Finalmente la función db.create_all() crea las tablas en nuestra base de datos con la estructura que definimos en los modelos.
Reinicia el servidor de desarrollo para que los cambios tengan efecto.
Finalizamos con la conexión. Seguimos con la definición de las queries, mutations, object types y los resolvers.
Las queries y mutations los vamos a definir en un paquete propio. Crea un directorio schemas y añade el correspondiente fichero __init__.py. Crea un archivo type_defs.py. Comenzaremos definiendo los object types.
Abre el fichero type_defs.py y inserta el siguiente código.
from ariadne import gql, ScalarType
from datetime import datetime
datetime_scalar = ScalarType("Datetime")
@datetime_scalar.serializer
def datetime_serializer(value):
return datetime.strptime(value,"%Y-%m-%dT%H:%M:%S")
type_defs = gql("""
scalar Datetime
type Author {
id: ID
name: String
lastname: String
books: [Book]
created_at: Datetime
updated_at: Datetime
}
type Book {
id: ID
title: String
author: Author!
created_at: Datetime
updated_at: Datetime
}
""")
La función gql nos provee una forma de validar los esquemas que definimos. ScalarType nos permite definir scalar types personalizados. Lo usaremos para definir el scalar Datetime para manejar fechas. La función datetime_serializer le dice a Ariadne el formato que queremos para las fechas.
En la variable type_defs que declaramos definimos los tipos Author y Book. Lo que podemos destacar en el tipo Author es el campo books, en él indicamos que retorna un arreglo de libros y puede ser nulo. En el tipo Book el campo author debe retornar un Author y no puede ser nulo.
Justo a continuación del tipo Book añadimos.
type_defs = gql("""
scalar Datetime
type Author {
id: ID
name: String
lastname: String
books: [Book]
created_at: Datetime
updated_at: Datetime
}
type Book {
id: ID
title: String
author: Author!
created_at: Datetime
updated_at: Datetime
}
type Query {
author(id: ID!): Author!
authors: [Author]
book(id: ID!): Book!
books: [Book]
}
""")
Las queries author(id: ID!): Author! y book(id: ID!): Book! retornan un objeto de tipo Author y Book respectivamente. Las queries authors: [Author] y books: [Book] retornan un arreglo de objetos de tipo Author y Book.
Continuamos con las mutaciones.
type_defs = gql("""
scalar Datetime
type Author {
id: ID
name: String
lastname: String
books: [Book]
created_at: Datetime
updated_at: Datetime
}
type Book {
id: ID
title: String
author: Author!
created_at: Datetime
updated_at: Datetime
}
type Query {
author(id: ID!): Author!
authors: [Author]
book(id: ID!): Book!
books: [Book]
}
type Mutation {
addAuthor(name: String!, lastname: String!): Author!
addBook(title: String!, author_id: ID): Book!
updateAuthor(id: ID!, name: String!, lastname: String!): Author!
updateBook(id: ID!, title: String!): Book!
deleteAuthor(id: ID!): Author!
deleteBook(id: ID!): Book!
}
""")
Las mutaciones addAuthor y addBook nos permiten añadir un autor y un libro respectivamente. updateAuthor y updateBook nos permiten actualizarlos y finalmente tenemos dos mutaciones más deleteAuthor y deleteBook para eliminarlos.
Finalmente debemos importar los tipos definidos en type_defs y el scalar personalizado datetime_scalar al fichero main.py
from schemas.type_defs import type_defs, datetime_scalar
Lo pasamos a la función make_executable_schema.
schema = make_executable_schema(type_defs, [query, datetime_scalar])
Antes de comenzar con los resolvers creamos las instancias de los esquemas que vamos a utilizar.
author_schema = AuthorSchema()
authors_schema = AuthorSchema(many=True)
book_schema = BookSchema()
books_schema = BookSchema(many=True)
Los esquemas author_schema y book_schema retornan un único objeto, mientras que los esquemas authors_schema y books_schema los usaremos para retornar un arreglo de objetos.
Ahora comenzamos con los resolvers para las consultas.
@query.field("authors")
def resolve_authors(_, info):
data = Author.query.all()
return authors_schema.dump(data)
@query.field("books")
def resolve_books(_, info):
data = Book.query.all()
return books_schema.dump(data)
@query.field("author")
def resolve_author(_, info, id):
data = Author.query.get(id)
return author_schema.dump(data)
@query.field("book")
def resolve_book(_, info, id):
data = Book.query.get(id)
return book_schema.dump(data)
El decorador @query.field() recibe un string con el nombre del query al que queremos vincular el resolver.
El resolver resolve_authors hace uso del modelo Author para recuperar todos los datos de la base de datos y los guarda en la variable data. Luego retornamos los datos serializado con authors_schema.dump.
El resolver para los libros hace lo mismo. El modelo Book recupera todos los registros y retorna los datos serializados con books_schema.dump.
El resolver resolve_author recibe un id. Mediante el modelo Author recuperamos el autor con ese id y lo guarda en data. Retornamos los datos serializados con author_schema.dump.
Los mismo para resolve_book. Recibe el id con el que el modelo Book obtiene el libro de la base de datos. Serializa los datos con book_schema.dump y los retorna.
Ahora continuamos con las mutaciones. Primero importamos las clase MutationType y pasamos la instancia a make_executable_schema.
from ariadne import QueryType, MutationType,graphql_sync, make_executable_schema
mutation = MutationType()
schema = make_executable_schema(type_defs, [query, mutation, datetime_scalar])
Ahora definimos los resolvers para las mutaciones.
@mutation.field("addAuthor")
def resolve_add_author(_, info, name, lastname):
author = Author(name=name, lastname=lastname)
db.session.add(author)
db.session.commit()
return author_schema.dump(author)
@mutation.field("addBook")
def resolve_add_book(_, info, title, author_id):
author = Author.query.get(author_id)
book = Book(title=title, author=author)
db.session.add(book)
db.session.commit()
return book_schema.dump(book)
@mutation.field("updateAuthor")
def resolve_update_author(_, info, id, name, lastname):
author = Author.query.get(id)
author.name = name
author.lastname = lastname
db.session.commit()
return author_schema.dump(author)
@mutation.field("updateBook")
def resolve_update_book(_, info, id, title):
book = Book.query.get(id)
book.title = title
db.session.commit()
return book_schema.dump(book)
@mutation.field("deleteAuthor")
def resolve_delete_author(_, info, id):
author = Author.query.get(id)
db.session.delete(author)
db.session.commit()
return author_schema.dump(author)
@mutation.field("deleteBook")
def resolve_delete_book(_, info, id):
book = Book.query.get(id)
book.author = None
db.session.delete(book)
db.session.commit()
return book_schema.dump(book)
El decorador @mutation.field() recibe un string con el nombre de la mutación al que queremos vincular el resolver.
resolve_add_author recibe name y lastname. Creamos una instancia del modelo Author, le pasamos los parámetros. Con db.session.add y db.session.commit añadimos el registro a la base de datos. Luego retornamos los datos del nuevo registro con author_schema.dump(author).
resolver_add_book es similar al anterior. Recibe title y author_id. Primero recuperamos el autor del libro por medio de Author.query.get(id) y lo guardamos en la variable author. Luego creamos una instancia del modelo Book y le pasamos el title y el author. Añadimos el registro y luego retornamos los datos del nuevo libro con book_schema.dump(book).
resolve_update_author recibe id, name y lastname. Con Author.query.get(id) recuperamos el autor y lo guardamos en author. Actualizamos los datos y luego con db.session.commit guardamos los cambios. Finalmente retornamos los datos del autor actualizado.
resolve_update_book recibe id y title. Obtenemos el libro con Book.query.get(id) y lo guardamos en la variable book. Actualizamos en título y con db.session.commit guardamos los cambio. Luego retornamos los datos del libro actualizado.
resolve_delete_author recibe un id. Obtenemos el autor que queremos eliminar con Author.query.get(id) y lo guardamos en la variable author. Por medio de db.session.delete(author) eliminamos el autor y guardamos los cambios con db.session.commit. Esto debe eliminar el autor y los libros que tiene. Retornamos los datos del autor eliminado.
resolve_delete_book recibe un id. Recuperamos el libro con Book.query.get(id) y lo guardamos en book. Antes de eliminar el libro debemos desvincularlo de su autor. Para ello establecemos a None el atributo book.author. Ahora sí, eliminamos el registro con db.session.delete(book). Esto debe eliminar el libro, pero no el autor. Finalmente retornamos los datos del libro eliminado.
Con esto finalizamos de construir el API Graphql, ahora es tiempo de ponerlo a prueba y ver su funcionalidad.
Comencemos reinicializando el servidor de desarrollo flask --app main run. Entra al endpoint 127.0.0.1:5000/graphql para ver el "playground".
Primer añadiremos algunos autores.
Observamos que definimos la mutación que queremos ejecutar, indicamos que recibe las variables $name y $lastname ambas de tipo String. En la parte inferior podemos ver la sección donde pasamos los valores a la mutación. Estoy insertando a "Agatha Christie". También voy a insertar a "Wilbur Smith". Podemos ver los registros en la tabla.
Excelente, ahora probemos insertar algunos libros de los autores.
Definimos otra mutación para añadir un libro, e indicamos que recibe las variables $title de tipo String y $id de tipo ID. En la sección de variables pasamos el título del libro y el id del autor. En este caso "Muerte en el Nilo", que pertenece a "Agatha Christie". También voy a añadir "Asesinato en el Orient Express" de la misma autora y "Muere un gorrión" de "Wilbur Smith". Podemos ver los registros en la tabla.
Seguimos probando las mutaciones para actualizar datos del autor.
Al igual que en los ejemplos anteriores definimos la mutación que queremos y definimos las variables que recibe. En la sección de variables indicamos que queremos modificar los valores del autor con id 1. Paso cualquier valor ya que es solo para verificar la funcionalidad. Lo vemos en la tabla.
Todo bien hasta ahora, seguimos con la actualización de los libros.
Estoy modificando el título del libro con id 1. En este caso es el mismo nombre pero en inglés. Lo vemos en la tabla.
Antes de probar las mutaciones para eliminar datos, voy a proba las consultas. Empecemos recuperando los autores.
Definimos la consulta e indicamos que además de los datos del autor queremos ver los libros que tienen.
Ahora probamos la consulta de un autor por su id.
Definimos la consulta para obtener un autor y le pasamos el correspondiente id. Además de los datos del autor, recuperamos los títulos de sus libros.
Probamos la funcionalidad para obtener todos los libros.
Además del título del libro obtenemos los datos del autor.
Ahora probamos obtener un libro por su id.
Recuperamos los datos del libro y además los datos del autor.
Nos toca probar las mutaciones para eliminar datos. Comencemos eliminando un libro.
Definimos la mutación para eliminar un libro y le pasamos el id. Lo vemos en la tabla, eliminamos el libro con id 3. Recordemos que esta mutación no elimina el autor.
Ahora eliminamos un autor.
Definimos la mutación para eliminar un autor y pasamos el id. Lo vemos en las tablas.
Aquí podemos observar que no solo elimina el autor, sino que también elimina los libros que le pertenecen, por lo que la tabla books queda vacía.
Excelente, hemos concluido con las pruebas y comprobamos que todas las funcionalidades se ejecutan correctamente.
Hemos finalizado con el proyecto. En este tutorial hemos repasado de manera práctica los principales conceptos para tener un API Graphql completamente funcional en python. Aprendimos a integrar Flask con Ariadne, y además, vimos como integrar Flask-SQLAlchemy con Flask-Marshmallow para generar tablas relacionales y poder serializar los datos.
Puedes encontrar proyecto completo en mi repositorio de GitHub haciendo clic AQUÍ.
Espero que lo hayas encontrado entretenido, instructivo y claro. Si tienes alguna duda, puedes hacérmelo saber en los comentarios. Pronto estaré subiendo más tutoriales.
Nos vemos en la próxima. Saludos!👋😊