Documentar la API y primeros endpoints - Episodio 27

Intentar consumir una API sin documentación es como navegar sin brújula.

Es decir, no saber qué endpoints existen, qué datos envían o cómo estructurar las peticiones solo genera frustración.

Por eso, documentar la API para endpoints desde el inicio no es un lujo, sino una necesidad.

Y aquí estoy para contarte cómo lo hice y las herramientas que facilitaron el proceso.🚀

📅 Diario de un SaaS – La API comenzaba a tomar forma, pero necesitaba estructura y documentación.

Ahora mismo estoy redactando el post nº 27.

Esto quiere decir que he librado mínimo 26 batallas anteriores de esta gran guerra de montar un SaaS desde 0.

Y además, no sé cuántos post me quedan más pero creo que es conveniente y prudente empezar a documentar el funcionamiento de la API.

🔥 La API funcionaba, pero... sin documentación ni control

Cuando los primeros endpoints empezaron a responder correctamente, sentí la primera victoria.

Pero enseguida me di cuenta de un problema:

• No había documentación clara para entender qué datos enviaba cada endpoint.
• Los entornos tenían versiones diferentes de dependencias, lo que generaba errores inesperados.
• Algunos puertos ya estaban ocupados, impidiendo que la API se ejecutara correctamente.

Era momento de ordenar todo antes de que el caos se apoderara del backend. 🚀

⚠️ Problemas encontrados antes de documentar la API

🔹 Endpoints funcionando, pero sin especificaciones claras

• Si alguien más intentaba consumir la API, no tenía ni idea de cómo usarla.
• Era necesario definir correctamente los métodos, parámetros y respuestas.

🔹 Errores por versiones diferentes de Python y dependencias

• En mi entorno local funcionaba, pero en el VPS algunas librerías daban errores.
• Había que unificar las versiones y registrar todas las dependencias.

🔹 Puertos ocupados bloqueaban el despliegue

• PostgreSQL y otros servicios estaban usando algunos puertos necesarios para Flask.
• Tenía que reasignar los puertos y evitar conflictos.

Había que ordenar la API antes de seguir añadiendo funcionalidades.

🛠️ Soluciones Implementadas

🔹 1. Configuración de Swagger para documentar la API

Para evitar que la API fuera una caja negra, implementamos Swagger:

pip install flask-swagger-ui

Luego, agregamos la documentación en app.py:

from flask_swagger_ui import get_swaggerui_blueprint

SWAGGER_URL = '/api/docs'
API_URL = '/static/swagger.json'

swagger_ui = get_swaggerui_blueprint(SWAGGER_URL, API_URL)
app.register_blueprint(swagger_ui, url_prefix=SWAGGER_URL)

Ahora, accediendo a /api/docs, la API mostraba su documentación interactiva. 📝

✅ Beneficio: Cualquier desarrollador podía probar y entender los endpoints sin revisar código.

🔹 2. Registro y corrección de dependencias

Para evitar inconsistencias entre entornos, creamos un archivo de dependencias:

pip freeze > requirements.txt

En el VPS, instalamos todo con:

pip install -r requirements.txt

✅ Beneficio: Ahora, todos los entornos usan las mismas versiones de librerías.

🔹 3. Implementación de los primeros endpoints: /register y /login

Para gestionar usuarios, creamos los endpoints de autenticación:

@app.route('/register', methods=['POST'])
def register():
    data = request.get_json()
    hashed_password = bcrypt.generate_password_hash(data['password']).decode('utf-8')
    new_user = User(username=data['username'], email=data['email'], password=hashed_password)
    db.session.add(new_user)
    db.session.commit()
    return jsonify({'message': 'Usuario registrado exitosamente'}), 201

Y el login:

@app.route('/login', methods=['POST'])
def login():
    data = request.get_json()
    user = User.query.filter_by(email=data['email']).first()
    if user and bcrypt.check_password_hash(user.password, data['password']):
        access_token = create_access_token(identity=user.username, expires_delta=timedelta(hours=1))
        return jsonify({'access_token': access_token}), 200
    return jsonify({'error': 'Credenciales incorrectas'}), 401

✅ Beneficio: Ahora, la API permitía registrar y autenticar usuarios.

🔹 4. Solución de problemas con puertos ocupados

Para evitar conflictos, verificamos qué procesos estaban usando los puertos:

sudo netstat -tulnp | grep LISTEN

Si un puerto estaba ocupado, lo liberamos:

sudo kill -9 <PID>

Y configuramos Flask para correr en un puerto diferente:

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5001)

✅ Beneficio: La API ya no se veía bloqueada por puertos ocupados.

💡 Lecciones aprendidas al documentar la API

🔹 1. La documentación es tan importante como el código

No sirve de nada tener una API funcional si nadie sabe cómo usarla.

🔹 2. Versionar dependencias evita problemas futuros

Sin requirements.txt, las diferencias entre entornos pueden romper la API.

🔹 3. Los puertos ocupados pueden ser un dolor de cabeza

Antes de desplegar, siempre hay que verificar qué servicios están corriendo en el servidor.

💡 Conclusión y Reflexión

🔹 Conclusión

La documentación y organización de una API no es un extra, es una necesidad.

Así que con Swagger, la API ahora es accesible para cualquier desarrollador.

Y además, al unificar dependencias y gestionar los puertos, aseguramos estabilidad en el despliegue.

🔹 Reflexión

Cuando inicias un proyecto, es fácil enfocarse en hacer que las cosas funcionen rápidamente.

Pero eso sí, si no te tomas el tiempo de documentar y optimizar, terminarás atrapado en problemas evitables.

Y ya sabes lo que dicen....cada minuto invertido en una buena estructura ahorra horas de dolores de cabeza en el futuro. 🚀

⏩ Próximos pasos

Ando pensando en los próximos pasos si será sobre:

📀 Balanceo de carga y escalabilidad del backend

📀 Implementación de backups automáticos en PostgreSQL

Cada mejora hace que la API sea más robusta y escalable. 🚀

 

Si quieres conocer otros artículos parecidos a Documentar la API y primeros endpoints - Episodio 27 puedes visitar la categoría Proyecto-IA.