API MikroTik RouterOS: automatiza tu red con la REST API v7

Si operas una red MikroTik con decenas o cientos de equipos, en algún momento chocas con el mismo muro: configurar, auditar y monitorear router por router a mano no escala. Aprovisionar un cliente PPPoE, leer el estado de una sesión BGP o cambiar una regla de firewall en 40 CCR desde WinBox es lento y propenso a error. La API MikroTik RouterOS existe justamente para eso, y desde RouterOS v7 tienes una alternativa mucho más cómoda que la API binaria tradicional: la REST API, una interfaz sobre HTTP que puedes consumir con curl, Python o cualquier stack que hable JSON. En este artículo revisamos cómo funciona, cómo habilitarla de forma segura y qué operaciones reales soporta.

Qué es la REST API de RouterOS v7 (y en qué se diferencia de la API binaria)

El término REST API se refiere a una API accesible vía protocolo HTTP a través de un conjunto de URLs orientadas a recursos. En RouterOS está implementada como un wrapper JSON sobre la API binaria de siempre: te permite crear, leer, actualizar y eliminar recursos, además de invocar comandos arbitrarios de consola. Dicho de otra forma, casi todo lo que haces en la terminal de RouterOS tiene un equivalente por REST.

La diferencia práctica con la API binaria clásica (puertos TCP 8728 y 8729) es el transporte. La REST API viaja sobre el servicio web del router, así que no necesitas una librería que implemente el protocolo de sentencias de MikroTik: te basta un cliente HTTP. Cada menú de RouterOS se mapea a una ruta bajo /rest. Por ejemplo, /ip/address/print en consola equivale a un GET sobre /rest/ip/address.

Un detalle del formato que conviene tener presente desde el inicio: en las respuestas JSON todos los valores se codifican como strings, incluso los números y booleanos. Es decir, "disabled":"false" es la cadena "false", no un booleano nativo. Si integras esto con código, valida y castea; no asumas tipos. Tampoco se soportan números con exponente.

Cómo habilitar la API MikroTik RouterOS de forma segura

Para empezar a usar la REST API debes habilitar el servicio www o www-ssl en el menú /ip/service. Con www-ssl activo (HTTPS) te conectas a https://<router_IP>/rest; con www (HTTP plano) a http://<router_IP>/rest.

Aquí va la primera decisión de diseño, y es importante: no uses HTTP plano en producción. El propio manual lo advierte: sobre www, las credenciales de autenticación pueden ser leídas por un atacante que capture el tráfico de forma pasiva. HTTP solo es aceptable para pruebas en una red donde nadie más tiene acceso, o cuando va encapsulado dentro de un túnel cifrado. Para todo lo demás, www-ssl con un certificado válido configurado en el menú de certificados.

La autenticación usa HTTP Basic Auth con el mismo usuario y contraseña de un usuario de consola. Y aquí entra la segunda buena práctica: no expongas la REST API con el usuario admin. Crea un usuario dedicado para automatización con un grupo que tenga la política rest-api (y solo los permisos que realmente necesita). El acceso vía REST se controla con esa política específica:

/user/group/add name=automation policy=read,rest-api,api,test,!write,!policy,!ftp

/user/add name=api-bot group=automation password=<clave-fuerte>

# Restringe el servicio web a tu subred de gestión y usa TLS
/ip/service/set www-ssl certificate=cert-mgmt address=10.10.0.0/24 disabled=no
/ip/service/set www disabled=yes

El parámetro address= en /ip/service limita desde qué red se acepta la conexión: úsalo siempre para que la API solo responda a tu segmento de NOC o a la IP del orquestador. Combinado con reglas de firewall al puerto del servicio web, reduces la superficie de ataque a lo mínimo. Si operas una plataforma de abonados, este mismo patrón es el que te permite automatizar el ciclo de vida de clientes PPPoE sin darle credenciales de administrador total a un script.

Métodos HTTP y el mapeo CRUD de RouterOS

La REST API traduce los verbos HTTP a los comandos de consola de RouterOS. Esta es la correspondencia exacta:

Verbo HTTP	CRUD	Comando RouterOS	Uso
GET	Read	print	Obtener todos los registros o uno solo de un menú.
PUT	Create	add	Crear un registro nuevo (uno por request).
PATCH	Update	set	Modificar un registro existente.
DELETE	Delete	remove	Eliminar un registro por su ID.
POST	—	(cualquiera)	Método universal para acceder a todos los comandos de consola.

Ese último, POST, es la llave maestra: todo lo que expone la API está disponible por POST, incluyendo comandos de acción como ping, bandwidth-test o reinicios de interfaz, que no encajan en el modelo CRUD puro.

Ejemplos reales de la API MikroTik RouterOS con curl

Lo mejor de la REST API es lo directo que resulta probarla. Un GET para leer el estado del sistema (equivalente a /system/resource/print):

# Leer recursos del sistema
curl -k -u api-bot: https://10.155.101.214/rest/system/resource

# Listar todas las direcciones IP (equivale a /ip/address/print)
curl -k -u api-bot: https://10.155.101.214/rest/ip/address

# Filtrar por propiedades directamente en la URL
curl -k -u api-bot: "https://10.155.101.214/rest/ip/address?network=10.155.101.0&dynamic=true"

# Traer solo las propiedades que te interesan con .proplist
curl -k -u api-bot: "https://10.155.101.214/rest/ip/address?.proplist=address,disabled"

Para crear un registro usas PUT con un cuerpo JSON; para modificar, PATCH apuntando al .id del registro; y para eliminar, DELETE:

# Crear una IP en una interfaz (PUT = add)
curl -k -u api-bot: -X PUT https://10.155.101.214/rest/ip/address \
  --data '{"address":"192.168.111.111","interface":"dummy"}' \
  -H "content-type: application/json"

# Agregar un comentario a un registro existente (PATCH = set)
curl -k -u api-bot: -X PATCH https://10.155.101.214/rest/ip/address/*3 \
  --data '{"comment":"gestion"}' -H "content-type: application/json"

# Eliminar un registro por ID (DELETE = remove)
curl -k -u api-bot: -X DELETE https://10.155.101.214/rest/ip/address/*9

Un par de comportamientos que importan al escribir código: en un PATCH o PUT exitoso, el servidor te devuelve el objeto actualizado o creado con todos sus parámetros, así que puedes confirmar el resultado sin una segunda llamada. En cambio, un DELETE exitoso responde con cuerpo vacío; si repites el borrado de un ID que ya no existe, el router devuelve {"error":404,"message":"Not Found"}. Maneja ese 404 como idempotencia, no como falla.

Consultas avanzadas, proplist y el límite de 60 segundos

Cuando necesitas lógica de filtrado más rica que un simple igual, usas POST sobre el comando print con dos claves especiales: .proplist (qué propiedades devolver) y .query (un stack de consulta con operadores). Por ejemplo, traer .id, address e interface de todos los registros dinámicos o de la red indicada:

curl -k -u api-bot: -X POST https://10.155.101.214/rest/ip/address/print \
  --data '{".proplist":[".id","address","interface"],
           ".query":["network=192.168.111.111","dynamic=true","#|"]}' \
  -H "content-type: application/json"

Ese .query es el mismo stack de consulta de la API binaria (el #| es un OR lógico), lo que te da paridad total con lo que harías por el protocolo nativo, pero en JSON.

Hay un límite operativo que debes conocer sí o sí: el timeout de la REST API es de 60 segundos. Si lanzas un comando que corre indefinidamente, la sesión se cierra con error. Por eso, comandos como ping o bandwidth-test requieren que acotes su duración. Un ping sin count devuelve {"error":400,"message":"Bad Request"} al agotar el tiempo; con count funciona:

curl -k -u api-bot: -X POST https://10.155.101.214/rest/ping \
  --data '{"address":"10.155.101.1","count":"4"}' \
  -H "content-type: application/json"

Interioriza esto al diseñar automatizaciones: cualquier tarea larga hay que trocearla o acotarla con un parámetro de duración/cantidad, porque el límite de 60 s aplica aunque el comando pida correr más tiempo. En la práctica, esto empuja a un patrón asíncrono: disparas la acción, guardas el .id o el resultado que devuelve la respuesta y consultas el estado en llamadas separadas, en vez de mantener una conexión abierta esperando que el equipo termine.

Dónde encaja la REST API en una operación real

La REST API no reemplaza el diseño de red: lo potencia. Con ella puedes construir aprovisionamiento automático de clientes, auditorías de configuración periódicas, recolección de métricas para tu stack de observabilidad o pipelines de cambios versionados en Git. Es la base natural para proyectos de automatización de RouterOS donde antes dependías de scripts internos y exportaciones manuales. Un solo endpoint HTTP, autenticado y restringido por subred, te abre toda la superficie de configuración del router de forma programática.

¿Binaria o REST? No es una elección excluyente. La API binaria sobre api-ssl sigue siendo más eficiente para volúmenes altos —soporta tagging para ejecutar comandos en paralelo y es más liviana por request—, así que para sincronizar miles de sesiones PPPoE cada pocos minutos suele rendir mejor. La REST API brilla en integraciones ad-hoc, webhooks, dashboards y cualquier equipo que ya vive en HTTP/JSON y no quiere cargar con una librería del protocolo binario. En flotas grandes es común combinar ambas según el caso de uso.

Ahora bien, la parte difícil no es hacer el primer curl funcionar: es diseñar el modelo de permisos, la segmentación de gestión, la idempotencia de los cambios y la recuperación ante errores para que la automatización sea segura en producción y no un riesgo. Un usuario rest-api mal acotado o un servicio web expuesto a Internet es una puerta de entrada, no una comodidad. Ahí es donde conviene un diseño pensado por alguien que opera estas redes a diario, tema que abordamos en nuestra consultoría de ingeniería MikroTik.

En MikroTik Chile ayudamos a equipos de TI, NOC e ISP a llevar la API MikroTik RouterOS desde una prueba de concepto a una plataforma de automatización robusta: aprovisionamiento de abonados, auditoría de flotas y control de cambios con la seguridad que exige una red de misión crítica. Si estás evaluando ordenar tu operación con RouterOS v7, conversemos sobre tu caso en soporte y operación continua.