Estandarización de Servicios

1. Estructura de Respuesta

Todos los servicios deben seguir una estructura de respuesta estándar en formato JSON:

{

    "success": false,

    "message": "Mensaje de servicio",

    "data": []

}

Reglas para la Respuesta:

success: Indica si la operación fue exitosa (true o false).
message: Mensaje claro y descriptivo sobre el resultado de la operación.
data: Contiene la información devuelta por el servicio. Si no hay datos, debe ser un array vacío ([]).

✅ Ejemplo de Respuesta Exitosa:

{

    "success": true,

    "message": "User retrieved successfully",

    "data": {

        "id": 1,

        "name": "John Doe",

        "email": "johndoe@example.com"

    }

}

✅ Ejemplo de Respuesta con Error:

{

    "success": false,

    "message": "User not found",

    "data": []

}

2. Generación de Documentación (Swagger)

Todo servicio debe contar con su respectiva documentación en Swagger.
La documentación debe incluir:

Descripción clara del servicio.
Parámetros requeridos y opcionales.
Ejemplos de respuestas esperadas.
Códigos de estado HTTP posibles.

✅ Ejemplo de Documentación Swagger en OpenAPI 3.0 (YAML):

paths:

  /users/{id}:

    get:

      summary: Get user by ID

      description: Retrieves a user using their unique ID.

      parameters:

        - name: id

          in: path

          required: true

          schema:

            type: integer

      responses:

        "200":

          description: User retrieved successfully

          content:

            application/json:

              schema:

                type: object

                properties:

                  success:

                    type: boolean

                  message:

                    type: string

                  data:

                    type: object

                    properties:

                      id:

                        type: integer

                      name:

                        type: string

                      email:

                        type: string

        "404":

          description: User not found

          content:

            application/json:

              schema:

                type: object

                properties:

                  success:

                    type: boolean

                  message:

                    type: string

                  data:

                    type: array

                    items: {}

3. Códigos de Estado HTTP Estándar

200 OK - Solicitud exitosa.
500 Internal Server Error - Error interno del servidor.

4. Seguridad y Buenas Prácticas

Validar siempre los datos de entrada antes de procesarlos.
Evitar exponer información sensible en los mensajes de error.

5. Uso de Estructuras de Control

Para mejorar la consistencia y calidad del código, se deben seguir estas reglas al manejar estructuras de control:

Condicionales (if/else)

Evitar múltiples anidaciones innecesarias.
Utilizar early return para mejorar la legibilidad.

✅ Ejemplo Correcto:

if not user:

    return {"success": false, "message": "User not found", "data": []}

return {"success": true, "message": "User retrieved", "data": user}

🚫 Ejemplo Incorrecto:

if user:

    return {"success": true, "message": "User retrieved", "data": user}

else:

    return {"success": false, "message": "User not found", "data": []}

Bucles (for, while)

Utilizar comprensiones de listas cuando sea posible.
Evitar bucles anidados innecesarios.

✅ Ejemplo Correcto:

even_numbers = [x for x in numbers if x % 2 == 0]

🚫 Ejemplo Incorrecto:

even_numbers = []

for x in numbers:

    if x % 2 == 0:

        even_numbers.append(x)