Guías Técnicas

Guía Paso a Paso para Crear una API RESTful con Flask-RESTful

Flask-RESTful es una extensión del framework Flask que facilita la creación de APIs REST de manera estructurada. Proporciona una forma sencilla de manejar recursos y responder en formato JSON.

🚀 ¿Cómo funciona Flask-RESTful?

Se define una aplicación Flask y se integra la API

  Flask-RESTful

  • Recurso: Un recurso es cualquier entidad que puede ser representada en tu API, como un usuario, un producto, o un préstamo.
  • Endpoints: Cada recurso se asocia a una o varias rutas y define cómo responder a los métodos HTTP (GET, POST, etc.).
  • Clases: Los recursos se definen como clases que heredan de Resource.

Flask-RESTful agrega una capa sobre Flask usando la clase Api, que se encarga de gestionar los recursos.

bash 
from flask import Flask
from flask_restful import Api

app = Flask(__name__)
api = Api(app)  # Se crea una API RESTful

🔧 Instalación de Flask y Flask-RESTful

Antes de comenzar, asegúrate de tener Python instalado en tu sistema.

Para instalar Flask y Flask-RESTful, ejecuta el siguiente comando:

bash 
pip install flask flask-restful

Si deseas trabajar en un entorno virtual, crea uno y actívalo antes de la instalación:

bash 
python -m venv venv
source venv/bin/activate  # En macOS/Linux
doskey activate=venvScriptsactivate  # En Windows
pip install flask flask-restful

📌 3. Crear una API REST con Flask-RESTful

Crea el archivo app.py y agrega el siguiente código:

python 
from flask import Flask, request
# Se importan Resource y Api. Resource permite definir endpoints como clases, y Api gestiona las rutas en Flask-RESTful.
from flask_restful import Resource, Api 


app = Flask(__name__)
api = Api(app)  # Se crea una API RESTful

# Base de datos simulada
usuarios = []

# Se define un recurso de la API como una clase, heredando de Resource para manejar peticiones HTTP.
class UsuarioResource(Resource):
  # Método que maneja solicitudes GET y devuelve la lista de usuarios.
  def get(self):
      """Obtiene la lista de usuarios"""
      return {"usuarios": usuarios}, 200  # Devuelve la lista de usuarios en formato JSON con código 200 (OK)

  # Método que maneja solicitudes POST y agrega un nuevo usuario a la base de datos.
  def post(self):  
      """Agrega un nuevo usuario"""
      data = request.get_json()  # Obtiene los datos enviados en formato JSON
      if "nombre" not in data:
          return {"mensaje": "El campo 'nombre' es obligatorio"}, 400  # Devuelve un error 400 si falta el campo "nombre"

      usuario = {"id": len(usuarios) + 1, "nombre": data["nombre"]}  # Crea un nuevo usuario con ID autoincremental  
      usuarios.append(usuario)  # Agrega el usuario a la lista  
      return usuario, 201  # Retorna el usuario creado con código 201 (Created)


# Se define un recurso de la API para manejar detalles de un usuario, heredando de Resource para gestionar peticiones HTTP.
class UsuarioDetalleResource(Resource):
  def get(self, usuario_id):
      """Obtiene los detalles de un usuario específico basado en su ID"""
      # Busca el usuario con el ID proporcionado en la lista de usuarios
      usuario = next((u for u in usuarios if u["id"] == usuario_id), None)
      
      # Si el usuario es encontrado, devuelve el usuario y un código de estado 200 (OK)
      if usuario:
          return usuario, 200
      
      # Si no se encuentra el usuario, devuelve un mensaje de error con un código de estado 404 (No encontrado)
      return {"mensaje": "Usuario no encontrado"}, 404

  def put(self, usuario_id):
      """Actualiza la información de un usuario existente utilizando su ID"""
      # Obtiene los datos JSON enviados en la solicitud para actualizar el usuario
      data = request.get_json()
      
      # Busca el usuario con el ID proporcionado
      for usuario in usuarios:
          if usuario["id"] == usuario_id:
              # Actualiza el campo "nombre" del usuario si está presente en los datos enviados
              usuario["nombre"] = data.get("nombre", usuario["nombre"])
              return usuario, 200  # Devuelve el usuario actualizado y un código de estado 200 (OK)
      
      # Si no se encuentra el usuario, devuelve un mensaje de error con un código de estado 404 (No encontrado)
      return {"mensaje": "Usuario no encontrado"}, 404

  def delete(self, usuario_id):
      """Elimina un usuario existente utilizando su ID"""
      global usuarios
      # Filtra la lista de usuarios eliminando el usuario con el ID proporcionado
      usuarios = [u for u in usuarios if u["id"] != usuario_id]
      
      # Devuelve un mensaje indicando que el usuario ha sido eliminado con un código de estado 200 (OK)
      return {"mensaje": "Usuario eliminado"}, 200


# Registrar la ruta en la API
api.add_resource(UsuarioResource, "/usuarios")
api.add_resource(UsuarioDetalleResource, "/usuarios/<int:usuario_id>")


if __name__ == "__main__":
  # Ejecuta la aplicación Flask solo si este archivo es ejecutado directamente
  app.run(debug=True)  # Inicia el servidor de desarrollo de Flask en modo debug para facilitar el desarrollo

4. Probar la API con cURL o Postman

Ejecuta la API:

bash 
python app.py

Ahora prueba los endpoints:

➤ Obtener todos los usuarios (GET)

bash 
curl -X GET http://127.0.0.1:5000/usuarios

📌 Respuesta:

json 
{"usuarios": []}

➤ Agregar un usuario (POST)

bash 
curl -X POST http://127.0.0.1:5000/usuarios -H "Content-Type: application/json" -d '{"nombre": "Carlos"}'

📌 Respuesta:

json 
{"id": 1, "nombre": "Carlos"}

➤ Obtener un usuario por ID (GET)

bash 
curl -X GET http://127.0.0.1:5000/usuarios/1

📌 Respuesta:

json 
{"id": 1, "nombre": "Carlos"}

➤ Actualizar un usuario por ID (PUT)

bash 
curl -X PUT http://127.0.0.1:5000/usuarios/1 -H "Content-Type: application/json" -d '{"nombre": "Juan"}'

📌 Respuesta:

json 
{"id": 1, "nombre": "Juan"}

➤ Eliminar un usuario por ID (DELETE)

bash 
curl -X DELETE http://127.0.0.1:5000/usuarios/1

📌 Respuesta:

json 
{"mensaje": "Usuario eliminado"}

❓ 5. Explicación del Código

  • Resource: Clase base de Flask-RESTful que permite definir recursos.
  • get(): Maneja las solicitudes GET.
  • post(): Recibe datos en JSON y agrega un usuario.
  • put(): Permite actualizar la información de un usuario.
  • delete(): Elimina un usuario por ID.
  • api.add_resource(UsuarioResource, "/usuarios"): Asigna la ruta a la API.
  • api.add_resource(UsuarioDetalleResource, "/usuarios/<int:usuario_id>"): Define rutas con variables.
  Ventajas de Flask-RESTful

  • ✔ Código más limpio y estructurado.
  • ✔ Manejo sencillo de rutas y recursos.
  • ✔ Integración con validaciones y respuestas en JSON.
  • ✔ Facilita la escalabilidad en proyectos grandes.

  Nota

En Python, self es un parámetro utilizado en los métodos de una clase. Es una convención que se usa para hacer referencia a la instancia actual de la clase dentro de sus métodos. Cada vez que se llama a un método de la clase, self permite acceder a las variables y métodos de esa instancia.

self: Se refiere al objeto actual de la clase en el que se está llamando el método get(). En resumen, self es simplemente una referencia al objeto actual y es necesario para acceder a sus propiedades y métodos dentro de la clase.

Por ejemplo, en el siguiente método de una clase:

bash 
def get(self, usuario_id):
  # código aquí