MIH API (Guía del Desarrollador)

La MIH API permite a otros plugins de Moodle despachar eventos o realizar peticiones a servicios registrados sin preocuparse del transporte subyacente, la autenticación o los patrones de resiliencia.

Concepto

En lugar de usar curl o guzzle directamente, usas la fachada mih. Esto asegura que tu petición sea registrada, monitoreada y reintentada automáticamente.

Uso

1. Petición Estática

La forma más simple de hacer una petición.

use local_integrationhub\mih;

try {
    $response = mih::request('slug-mi-servicio', '/api/users', ['id' => 123], 'POST');
    
    if ($response->is_ok()) {
        $data = $response->json();
        // ...
    }
} catch (\moodle_exception $e) {
    // Manejar servicio no encontrado o circuit breaker abierto.
}

2. Interfaz Fluida (Recomendado)

Una forma más legible de construir peticiones.

use local_integrationhub\mih;

$response = mih::send('slug-mi-servicio')
    ->to('/api/users')
    ->with(['id' => 123])
    ->dispatch();

Valor de Retorno

Devuelve un objeto \local_integrationhub\mih_response.

---

El Objeto mih_response

Propiedades

Propiedad	Tipo	Descripción
$success	bool	true si la petición se completó exitosamente (HTTP 2xx, o publicación AMQP exitosa)
$httpstatus	int|null	Código de respuesta HTTP. null para AMQP.
$body	string|null	Cuerpo de respuesta crudo como string. null si no hubo cuerpo.
$error	string|null	Mensaje de error legible. null en éxito.
$latencyms	int	Tiempo total desde inicio de petición hasta respuesta, en milisegundos. Incluye todos los delays de reintento.
$attempts	int	Número total de intentos realizados (1 = sin reintentos necesarios).

Métodos

is_ok(): bool

Devuelve true si $success === true.

json(bool $assoc = true): mixed

Decodifica $body como JSON. $assoc = true (por defecto): devuelve array asociativo. $assoc = false: devuelve stdClass.

---

Ejemplos de Uso

Petición POST Básica

$response = \local_integrationhub\mih::request(
    'mi-api',
    '/api/v1/eventos',
    [
        'tipo'     => 'usuario.login',
        'user_id'  => $USER->id,
        'tiempo'   => time(),
    ],
    'POST'
);

if ($response->is_ok()) {
    $resultado = $response->json();
} else {
    debugging("Integración fallida: {$response->error} (HTTP {$response->httpstatus})");
}

Publicar en AMQP

// El endpoint actúa como routing key
$response = \local_integrationhub\mih::request(
    'rabbitmq-prod',
    'events.course.completed',
    [
        'user_id'   => $userid,
        'course_id' => $courseid,
        'timestamp' => time(),
    ]
    // El método se ignora para AMQP
);

Llamada SOAP

// El endpoint es el nombre del método SOAP
$response = \local_integrationhub\mih::request(
    'erp-legado',
    'SincronizarUsuario',
    [
        'UserId'   => $userid,
        'NombreCompleto' => fullname($user),
        'Email'    => $user->email,
    ]
);

Patrón Completo de Manejo de Errores

function mi_plugin_sincronizar_usuario(int $userid): bool {
    global $DB;

    $user = $DB->get_record('user', ['id' => $userid], '*', MUST_EXIST);

    try {
        $response = \local_integrationhub\mih::request(
            'api-sincronizacion',
            '/usuarios',
            [
                'id'        => $user->id,
                'username'  => $user->username,
                'email'     => $user->email,
            ],
            'POST'
        );

        if ($response->is_ok()) {
            debugging("Usuario {$userid} sincronizado. Latencia: {$response->latencyms}ms");
            return true;
        }

        debugging("Fallo de sincronización: HTTP {$response->httpstatus} — {$response->error}");
        return false;

    } catch (\moodle_exception $e) {
        // Servicio no encontrado, desactivado o circuito abierto
        debugging("Error de Integration Hub: " . $e->getMessage(), DEBUG_DEVELOPER);
        return false;
    }
}

---

Uso de MIH en Tareas Programadas

La API MIH funciona dentro de tareas programadas y adhoc de Moodle:

class mi_plugin_tarea_sync extends \core\task\scheduled_task {

    public function get_name(): string {
        return 'Sincronizar usuarios con CRM externo';
    }

    public function execute(): void {
        global $DB;

        $usuarios = $DB->get_records('user', ['deleted' => 0, 'suspended' => 0]);

        foreach ($usuarios as $usuario) {
            try {
                $response = \local_integrationhub\mih::request(
                    'crm-api',
                    '/sync/usuarios',
                    ['id' => $usuario->id, 'email' => $usuario->email],
                    'POST'
                );

                if (!$response->is_ok()) {
                    mtrace("Fallo al sincronizar usuario {$usuario->id}: {$response->error}");
                }
            } catch (\moodle_exception $e) {
                mtrace("Error MIH para usuario {$usuario->id}: " . $e->getMessage());
                // Continuar con el siguiente usuario
            }
        }
    }
}