Documentacion API clara y desplegable

API para clientes moviles, aplicaciones de escritorio y automatizacion alrededor de una instancia Militant.

Instalador · Docker · Inicio rapido · Wiki · Seguridad

Instalacion

La forma mas simple es usar el instalador dedicado:

mkdir -p militant-api-install
cd militant-api-install
curl -fsSLO https://gitlab.com/militant1/api-installer/-/raw/main/militant-api
chmod +x militant-api
./militant-api

El script:

• conecta la API a la red Docker correcta
• conecta la API a la base principal
• gestiona el uso compartido de uploads
• genera .env.api
• genera docker-compose.api.yml

Comandos utiles:

• ./militant-api update
• ./militant-api uninstall

Guia dedicada: https://gitlab.com/militant1/api-installer

Requisitos

• la aplicación principal de Militant ya debe estar corriendo
• la API debe estar en la misma red de Docker
• la base de datos de Militant debe ser accesible
• si deseas los mismos archivos de medios, comparte también uploads

Fediverso (ActivityPub)

La API ahora expone una superficie Fediverso completa para móvil mediante v1/fediverse.php: perfil local, seguidores remotos, seguidos remotos, búsqueda de direcciones @usuario@instancia, resolución de perfiles remotos, acciones de seguir/dejar de seguir y un flujo sincronizado de publicaciones remotas. También activa automáticamente la transmisión ActivityPub al crear nuevas publicaciones usando Firmas HTTP RSA.

Ver documentación del Endpoint

Docker manual

Si prefieres gestionar Compose manualmente:

cp docker-compose.casaos.yml docker-compose.api.yml
docker compose -f docker-compose.api.yml up -d

Variables principales:

• DB_HOST o API_DB_HOST: host MySQL de la instancia Militant
• DB_NAME o API_DB_NAME: base de datos principal
• DB_USER / DB_PASSWORD: credenciales SQL
• MAIN_APP_HOST: URL interna de la web en la red Docker, por ejemplo http://militant-web:80
• API_UPLOADS_PATH: ruta interna de medios, normalmente /var/www/uploads
• API_CORS_ORIGINS: * o dominio(s) autorizados
• API_REQUIRE_HTTPS: true en produccion publica HTTPS

LiveKit (directos en video)

Para emitir tokens LiveKit en el servidor (POST /v1/lives.php?path=token), configura los secretos:

• Variables de entorno (recomendado en produccion): LIVEKIT_URL (wss://...), LIVEKIT_API_KEY, LIVEKIT_API_SECRET
• O archivo local ignorado por git: config/livekit.local.php (generado desde el panel web)
• Los detalles de un directo (GET /v1/lives.php?path={id}) pueden incluir background_image, editable por el creador mediante PUT /v1/lives.php?path={id}/background.

WebRTC / TURN (llamadas privadas, grupos, 4G/5G)

Para llamadas moviles fiables, especialmente en 4G/5G, configura un servidor TURN:

• Variables de entorno: WEBRTC_TURN_URLS, WEBRTC_TURN_AUTH_SECRET, WEBRTC_TURN_TTL, WEBRTC_TURN_REALM
• O archivo local ignorado por git: config/turn.local.php (generado desde el panel web)
• GET /v1/settings.php devuelve stun_servers, turn_servers y webrtc_ice_servers
• si WEBRTC_TURN_AUTH_SECRET esta configurado, la API genera credenciales TURN temporales HMAC (modo recomendado, compatible con coturn use-auth-secret)

Panel web (tras iniciar sesion con una cuenta de usuario Militant):

• .../admin/login.php luego .../admin/tokens.php
• .../admin/livekit.php: introducir las credenciales LiveKit (se requiere la contrasena de la cuenta para guardar) — solo tecnicos Militant (igual que la web: users.is_admin = 1; respaldo: is_technician o LIVEKIT_TECHNICIAN_USER_IDS)
• .../admin/turn.php: introducir la configuracion TURN / Coturn para la API y mostrar el bloque coturn para copiar
• En la web Militant, los tecnicos se gestionan en admin.php?tab=technicians (promocion / retiro de is_admin).

Ver tambien .env.example en GitLab para los nombres de variables.

Probar

Una vez iniciada la API:

• indice: http://localhost:9082/v1/index.php
• login admin de tokens: http://localhost:9082/admin/login.php
• configuracion LiveKit (tras login): http://localhost:9082/admin/livekit.php
• configuracion TURN (tras login): http://localhost:9082/admin/turn.php
• healthcheck: http://localhost:9082/health-public.php

Ejemplo:

curl http://localhost:9082/v1/index.php

Token rapido

curl -X POST http://localhost:9082/v1/auth.php \
  -H "Content-Type: application/json" \
  -d '{"username":"tu_usuario","password":"tu_password"}'

Usar el token:

curl http://localhost:9082/v1/posts.php \
  -H "Authorization: Bearer TU_TOKEN"

Sugerencias de funcionalidades

Endpoints disponibles:

GET /v1/feature_suggestions.php
GET /v1/feature_suggestions.php?filter=popular
GET /v1/feature_suggestions.php?id=12
GET /v1/feature_suggestions.php?action=stats
POST /v1/feature_suggestions.php
POST /v1/feature_suggestions.php?action=vote
POST /v1/feature_suggestions.php?action=comment
POST /v1/feature_suggestions.php?action=update_status
DELETE /v1/feature_suggestions.php?id=12

Ejemplo de creacion:

curl -X POST http://localhost:9082/v1/feature_suggestions.php \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Modo sin conexion",
    "description": "Permitir la consulta local de sugerencias y del estado cuando la red no esta disponible."
  }'

Respuestas y reacciones en la mensajeria

La mensajeria privada y los grupos de mensajeria ahora soportan:

• responder a un mensaje con parent_id
• reacciones de usuario en los mensajes
• devolver el mensaje padre y el resumen de reacciones en las listas

Endpoints disponibles:

GET /v1/messages.php?user_id=34
POST /v1/messages.php
POST /v1/messages.php?action=react
DELETE /v1/messages.php?action=react&message_id=56

GET /v1/message_groups.php?path=12/messages
POST /v1/message_groups.php?path=12/messages
POST /v1/message_groups.php?path=messages/78/reactions
DELETE /v1/message_groups.php?path=messages/78/reactions

Campos adicionales devueltos en mensajes privados:

• parent_id
• parent_content
• parent_sender_username
• reactions_summary
• user_reaction

Campos adicionales devueltos en mensajes de grupo:

• parent_id
• parent_content
• parent_username
• reactions_summary
• user_reaction

Ejemplo de respuesta a un mensaje privado:

curl -X POST http://localhost:9082/v1/messages.php \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 34,
    "content": "Respondo a tu mensaje",
    "parent_id": 56
  }'

Ejemplo de reaccion en un mensaje privado:

curl -X POST http://localhost:9082/v1/messages.php?action=react \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": 56,
    "reaction": "heart"
  }'

Ejemplo de respuesta en un grupo:

curl -X POST http://localhost:9082/v1/message_groups.php?path=12/messages \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Yo me encargo de este",
    "parent_id": 78
  }'

Mantenimiento

Si usas el instalador dedicado:

./militant-api update

Si no, con Docker Compose manual:

docker compose -f docker-compose.api.yml pull
docker compose -f docker-compose.api.yml up -d

Desinstalacion:

./militant-api uninstall

Bots

Para integraciones con bots y automatizaciones, empieza con el ejemplo incluido:

• Keyword Relay Bot

Leer mas

• DEMARRAGE_RAPIDE.md: primera prueba y primeras llamadas
• DOCKER.md: detalles de Docker y red
• GUIDE_SIMPLE.md: version muy corta
• WIKI.md: documentacion mas amplia de endpoints
• SECURITY.md: seguridad y notas de produccion

---