# Estandarización de Servicios

### 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)
```