Construyendo APIs REST utilizando Flask

A estas alturas ya deberías saber qué es una API REST, si no, te recomiendo leer sobre esto aquí.

A modo de breve resumen, construir una API de forma REST significa que tienes que construir sus endpoints de URL agrupados por "recursos". Un recurso es algo que quieres gestionar, por ejemplo: un estudiante, un usuario, un auto, etc. Un recurso es algo similar a una tabla de base de datos, pero los llamamos "recursos" debido a algunas excepciones.

Aquí hay un ejemplo de endpoints RESTful API para gestionar Estudiantes:

Método	URL	Descripción
GET	/estudiante	Debería devolver todos los estudiantes
GET	/estudiante/1	Debería devolver un solo estudiante con el id=1
GET	/cohort/1/estudiantes	Debería devolver todos los estudiantes de la clase con el id=1
POST	/estudiante	Debería crear un nuevo estudiante
PUT	/estudiante/1	Debería actualizar la información del estudiante con el id=1
DELETE	/estudiante/1	Debería eliminar al estudiante con el id=1

Echa un vistazo a las URL, ellas siguen un patrón. Después de un tiempo, los endpoints hablarán por sí mismos, tendrán sentido y podrás adivinar a lo que hacen o incluso adivinar algunos endpoints. Esa es la idea.

☝️ Puede leer más sobre las API REST en esta lección de BreatheCode.
Aquí hay un video de 8 minutos que explica REST: https://www.youtube.com/watch?v=7YcW25PHnAA

Ahora hablemos sobre Flask

¡Flask es increíble! Es muy similar al Servidor Express Node.js y eso lo hace aún más genial porque podrás trabajar con ambas tecnologías sin mucha curva de aprendizaje.

Flask es una librería para crear un servidor web y APIs. Básicamente, cuando ejecutas un script de Python que contiene las siguientes líneas, el computador comenzará a escuchar las solicitudes HTTP:

1from flask import Flask
2app = Flask(__name__)
3
4@app.route("/")
5def hello():
6    return "Hello World!"
7
8app.run(host='0.0.0.0')

Haz clic para probar este código en vivo.

Flask Hello-World explicado

1from flask import Flask  # Aquí importamos la librería Flask en nuestro archivo.
2app = Flask(__name__)  # Aquí creamos una nueva instancia del servidor Flask.
3
4@app.route("/")  # Aquí definimos el primer path de la API: GET /
5def hello()  # Este método se llamará cuando el cliente haga el request
6    return "Hello World!"  # Aquí flask devolverá "Hello World, esto podría ser un string HTML o un string JSON.
7
8app.run(host='0.0.0.0')  # Finalmente iniciamos el servidor en el localhost.
9

En Flask podemos agregar nuevos endpoints utilizando el decorador @ app.route, no te preocupes si esta es la primera vez que ves un decorador, el concepto es muy simple y aquí hay un video de 5 minutos explicándolo.

Agregando nuevos endpoints

Si deseas agregar otro endpoint a tu API que se ejecuta cuando un cliente haga el GET/person, tendrás que agregar otro bloque de código como este:

1@app.route("/person")  # Aquí especificamos la ruta para el endpoint.
2def handle_person()  # Aquí declaramos una función que se llamará cuando se realice una request a esa url
3    return "Hello Person!"  # Aquí especificamos el string que queremos responder al cliente.
4

Especificando el método: GET, PUT, POST, DELETE

Si deseas que tu endpoint responda a POST, PUT o DELETE, puedes especificarlo en el decorador de la siguiente manera:

1from flask import Flask, request
2
3@app.route("/person", methods=['POST', 'GET'])  # Aquí especificamos que estos endpoints aceptan solicitudes POST y GET.
4def handle_person():
5    if request.method == 'POST':  # Podemos entender qué tipo de request estamos manejando usando un condicional
6        return "Se recibió un POST"
7    else:
8        return "Se recibió un GET"
9

Respondiendo un cuerpo JSON

La respuesta puede ser básicamente lo que quieras siempre que sea un string: HTML, JSON, CSS, imágenes, etc. Solo asegúrate de convertir en string lo que quieras responder.

En el siguiente ejemplo, estamos utilizando el método jsonify para convertir un diccionario llamado person1 en un string JSON antes de devolverlo al cliente.

1from flask import Flask, jsonify
2
3@app.route("/person")
4def handle_person():
5    person1 = {"name": "Bob"}
6    return jsonify(person1)
7

El código de respuesta

El código de respuesta es 200 por defecto, y 500 si hay un error desconocido. Si deseas responder al cliente con un código diferente, deberás especificarlo así:

1from flask import Flask, jsonify
2
3@app.route("/person")
4def handle_person():
5    contenido = {"detalles": "Hubo un error en la solicitud"}
6    respuesta = jsonify(contenido)
7    respuesta.status_code = 400  # Aquí cambiamos el código de estado a 400 (código muy común en caso de errores de solicitud)
8    return respuesta
9

Otra forma de cambiar el código de respuesta usando una coma ,:

1@app.route("/person")
2def handle_person():
3    contenido = {"detalles": "Hubo un error en la solicitud"}
4    return jsonify(content), 400
5

Manejo de errores y validaciones

Pero ¿y si la solicitud viene con errores? Por ejemplo: si tenemos un endpoint para crear una persona y debemos especificar el first_name Y el last_name, pero solo se encontró el first_name en la solicitud, así es como lo validaríamos:

1@app.route('/person', methods=['POST'])
2def create_person():
3    # POST request
4    body = request.get_json()  # Obtener el request body de la solicitud
5    if body is None:
6        return "The request body is null", 400
7    if 'first_name' not in body:
8        return 'Especificar first_name',400
9    if 'email' not in body:
10        return 'Especificar last_name', 400
11    return "ok", 200

Definiendo un modelo

Hay diferentes maneras de integrar Flask en un servidor de base de datos, pero explicaremos la integración con SQL ALchemy.

Existe una gran librería de Python que integra Flask + SQLAlchemy de manera constante: Flask-SQLAlchemy. Nosotros te sugerimos que leasesta lección sobre SQLAlchemy primero y vuelve aquí.

Para integrar con SQLAlchemy, todo lo que tienes que hacer es instalar el paquete e importarlo a tus archivos de esta manera:

1from flask_sqlalchemy import SQLAlchemy
2db = SQLAlchemy()
3

Una vez que se importa, puedes comenzar a declarar tus modelos de base de datos de esta manera:

1class Person(db.Model):
2    id = db.Column(db.Integer, primary_key=True)
3    username = db.Column(db.String(80), unique=True, nullable=False)
4    email = db.Column(db.String(120), unique=True, nullable=False)
5
6    def __repr__(self):
7        return '<Person %r>' % self.username
8
9    def serialize(self):
10        return {"username": self.username,
11                "email": self.email}
12

Puedes añadir tantos modelos como quieras.

¿Listo para empezar a codificar?

Hemos preparado este ejemplo de codificación en vivo que puede ejecutar tu mismo en GitHub Codespaces o Gitpod y utilizarlo como base para su proyecto.

Flask Rest Hello: https://github.com/4GeeksAcademy/flask-rest-hello