Fa temps que, quan jugo amb iRedAdmin, m’interessa no quedar-me només amb la interfície web. Hi ha moments en què convé poder provar l’API, repetir operacions o inspeccionar respostes sense haver d’anar obrint pestanyes, copiant cookies i muntant comandes a mà.

D’aquí surt iredadmin_api_tools, i en concret el script iredapi_manager.py.

Va costar una mica, però em penso que ha quedat bastant reixit.

El repositori públic és aquí:

🔗 cuquet/iredadmin_api_tools a GitHub

Què és exactament

iredapi_manager.py és una eina de línia de comandes per interactuar amb l’API REST d’iRedAdmin.

La idea és simple: disposar d’una capa pràctica per fer des del terminal allò que sovint acabaries fent amb curl, però amb una mica més d’ordre:

  • iniciar sessió
  • guardar i reutilitzar cookies
  • fer crides GET, POST, PUT, DELETE i PATCH
  • consultar la sessió actual
  • tancar sessió
  • llegir JSON de forma més còmoda

Per a mi, aquest tipus d’eina té molt de sentit quan estàs desenvolupant o validant canvis sobre iRedAdmin i vols un flux més ràpid que no pas la navegació manual.

He de dir que funciona raonablement bé si instal·les 🗞️ iredadmin-modules. Per tal que el client sigui funcional cal afegir la capa de llibreries i controlers 😜

Ho comento perquè les dues peces encaixen molt bé:

  • iredadmin_modules amplia i ajusta l’entorn d’iRedAdmin
  • iredadmin_api_tools et dona una manera còmoda d’exercir i validar l’API des del terminal

Per tant, jo no ho veig com dos projectes separats, sinó com una combinació bastant natural: un modifica i enriqueix l’entorn, i l’altre et facilita provar-lo i administrar-lo.

Per què pot ser útil

El valor real no és només “fer crides HTTP”. Això ja ho pots fer amb qualsevol client. La gràcia és que aquí hi ha una mica de criteri d’administració al damunt:

  • emmagatzema les cookies de sessió
  • pot reintentar quan detecta sessió caducada
  • té sortida JSON amb format més llegible
  • permet amagar dades sensibles per defecte
  • incorpora opcions per depuració i treball en entorns locals

En altres paraules: és una eina pensada per treballar, no només per demostrar que l’API respon.

Les comandes principals

La CLI gira sobretot al voltant de quatre accions:

  • login
  • call
  • session
  • logout

I això ja cobreix una part molt gran del dia a dia.

Per exemple:

./iredapi_manager.py login -u admin@example.com
./iredapi_manager.py session
./iredapi_manager.py call -e /user/list
./iredapi_manager.py logout

També m’ha semblat interessant que la configuració es pugui controlar amb variables d’entorn com:

  • IREDAPI_URL
  • IREDAPI_RAW
  • IREDAPI_INSECURE
  • IREDAPI_DEBUG
  • IREDAPI_MASK_SENSITIVE

Això va bé quan treballes en laboratoris, entorns amb certificats propis o quan vols integrar la CLI dins scripts més grans.

Gestió de sessió i dades sensibles

Una de les parts que em sembla més encertada és que el script no es limita a “fer una crida i prou”, sinó que intenta gestionar la sessió amb una mica d’intel·ligència.

Pel que veureu al codi:

  • detecta redireccions cap a login
  • intenta entendre si la sessió ha caducat
  • esborra cookies si cal
  • pot forçar un nou login abans de repetir la petició

I, a més, amaga claus sensibles per defecte com:

  • password
  • 2FA_required
  • 2fa_secret
  • session_id

Una captura senzilla del comandament session ja deixa veure prou bé l’enfocament:

Consulta de sessió amb iredapi_manager.py

Això em sembla especialment útil en una eina d’administració, perquè és molt fàcil acabar deixant rastres en terminals, captures o logs.

També hi ha 2FA

Una altra cosa útil és que el projecte ha anat incorporant suport per treballar amb 2FA.

No és només una CLI de “login i llistat d’usuaris”, sinó una eina que ha anat creixent per cobrir casos més reals de manteniment. Aquesta part em sembla un bon senyal: vol dir que el projecte no s’ha quedat en una primera prova ràpida.

ℹ️ Ajuda

Consulta totes les opcions amb:

$ ./iredapi_manager.py --help

Sortida esperada:

usage: iredapi [-h] [-r] [--show-secrets] {login,call,logout,session} ...

🔐 CLI per a l'API iRedAdmin

Pots usar la variable d'entorn IREDAPI_INSECURE=1 per ignorar errors SSL o bé l'opció -k/--insecure.
La URL base per defecte és https://localhost/iredadmin però la pots canviar amb --url o IREDAPI_URL.
Si indiques -r / --raw, el JSON es mostra en cru (sense color ni tabulació).

optional arguments:
  -h, --help            show this help message and exit
  -r, --raw             Sortida RAW sense colors
  --show-secrets        Mostra valors sensibles com API token, contrasenyes, etc.

Subcomandes:
  {login,call,logout,session}
    login               Iniciar sessió i desa cookies
    call                Fer una crida a l'API
    logout              Esborra el fitxer de cookies
    session             Mostrar informació de sessió actual (autenticació opcional si no hi ha sessió)

Per a més ajuda, usa --help o ajuda subcomanda.
Per a més informació sobre les API, visita: https://iredmail.org/api.html

Quan la faria servir

Jo la trobo especialment útil en situacions com aquestes:

  • provar endpoints nous sense obrir la UI cada vegada
  • validar que un patch o un mòdul respon bé via API
  • automatitzar consultes o accions repetitives
  • depurar problemes de sessió o autenticació
  • fer “smoke tests” després d’instal·lar iredadmin_modules

Per aquest últim punt, de fet, vaig construir un script “smoke test” que crea usuaris, dominis, llistes de correu, … modifica i esborra. Però això ja és un altre article. 😅

Tancant 🪂

iredadmin_api_tools intenta resoldre una necessitat molt concreta i molt real: treballar amb iRedAdmin des del terminal d’una manera menys rudimentària.

No intenta substituir-ho tot, ni fer veure que és una plataforma enorme. Fa una cosa útil, la fa bastant bé i sobretot té sentit dins d’un entorn on ja he començat a personalitzar i ampliar iRedAdmin.

I aquí és just on em sembla que brilla més: com a company natural de iredadmin_modules. 🤗