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
¡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 computar 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.
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!" #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.
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.
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.
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"
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 = { 6 "name": "Bob" 7 } 8 return jsonify(person1)
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 = { 6 "detalles": "Hubo un error en la solicitud" 7 } 8 resp = jsonify(contenido) 9 resp.status_code = 400 # aquí cambiamos el código de estado a 400 (código muy común en caso de errores de solicitud) 10 return resp
Otra forma de cambiar el código de respuesta usando una coma ,:
1@app.route("/person") 2def handle_person(): 3 contenido = { 4 "detalles": "Hubo un error en la solicitud" 5 } 6 return jsonify(content), 400
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 12 return "ok", 200
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()
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 { 11 "username": self.username, 12 "email": self.email 13 }
Puedes añadir tantos modelos como quieras.
Hemos preparado este ejemplo de codificación en vivo que puede ejecutar tu mismo en Gitpod y utilizarlo como base para su proyecto.
Flask Rest Hello: https://github.com/4GeeksAcademy/flask-rest-hello