Documentation API claire et deployable

API REST pour clients mobiles, desktop et automatisation autour d'une instance Militant.

Installer · Docker · Demarrage rapide · Wiki · Securite

Fonctionnalites exposees notamment :

• auth et profils utilisateurs
• posts, commentaires, reactions et bookmarks
• groupes, pages, events et stories
• fediverse / ActivityPub
• suggestions de fonctionnalites avec votes, commentaires et statuts
• lives et appels audio/video

Installer

Le plus simple est d'utiliser l'installateur dedie :

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

Le script configure :

• rejoint le bon reseau Docker
• connecte l'API a la base principale
• gere le partage des uploads
• gere la persistance de la configuration (config/)
• genere .env.api
• genere docker-compose.api.yml

Commandes utiles :

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

Guide dedie : https://gitlab.com/militant1/api-installer

Prerequis

• l'app principale Militant doit deja tourner
• l'API doit etre sur le meme reseau Docker
• la base de donnees Militant doit etre accessible
• si tu veux les memes medias, partage aussi uploads

Fediverse (ActivityPub)

L'API expose désormais un vrai espace Fediverse mobile via v1/fediverse.php : profil local, abonnés, abonnements distants, recherche d'adresses @user@instance, résolution de profils distants, suivi/désabonnement, et flux des publications distantes synchronisées. Elle déclenche aussi automatiquement la diffusion ActivityPub lors de la création de nouveaux posts via HTTP Signatures RSA.

Voir la documentation de l'Endpoint

Docker manuel

Si tu veux gerer le compose toi-meme :

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

Variables principales :

• DB_HOST ou API_DB_HOST : hote MySQL de l'instance Militant
• DB_NAME ou API_DB_NAME : base principale
• DB_USER / DB_PASSWORD : identifiants SQL
• MAIN_APP_HOST : URL interne de l'app web sur le reseau Docker, ex. http://militant-web:80
• API_UPLOADS_PATH : chemin interne vers les medias, generalement /var/www/uploads
• API_CORS_ORIGINS : * ou domaine(s) autorise(s)
• API_REQUIRE_HTTPS : true en production publique HTTPS

LiveKit (lives video)

Pour generer des tokens LiveKit cote serveur (POST /v1/lives.php?path=token), configure les secrets :

• Variables d'environnement (recommande en prod) : LIVEKIT_URL (wss://...), LIVEKIT_API_KEY, LIVEKIT_API_SECRET
• Ou fichier local ignore par git : config/livekit.local.php (genere depuis le panneau web). Note : En Docker, assurez-vous de monter un volume sur le dossier config/ pour ne pas perdre ces reglages.
• Les details d'un live (GET /v1/lives.php?path={id}) peuvent inclure background_image, modifiable par le createur via PUT /v1/lives.php?path={id}/background.

WebRTC / TURN (appels prives, groupes, 4G/5G)

Pour les appels mobiles fiables, surtout en 4G/5G, configurez un serveur TURN :

• Variables d'environnement : WEBRTC_TURN_URLS, WEBRTC_TURN_AUTH_SECRET, WEBRTC_TURN_TTL, WEBRTC_TURN_REALM
• Ou fichier local ignore par git : config/turn.local.php (genere depuis le panneau web)
• GET /v1/settings.php renvoie stun_servers, turn_servers et webrtc_ice_servers
• si WEBRTC_TURN_AUTH_SECRET est configure, l'API genere des credentials TURN temporaires HMAC (mode recommande, compatible coturn use-auth-secret)

Panneau web (apres connexion avec un compte utilisateur Militant) :

• .../admin/login.php puis .../admin/tokens.php
• .../admin/livekit.php : saisie des credentials LiveKit (mot de passe du compte requis pour enregistrer) — reserve aux techniciens Militant (comme sur le web : users.is_admin = 1 ; secours : users.is_technician = 1 ou LIVEKIT_TECHNICIAN_USER_IDS)
• .../admin/turn.php : saisie de la configuration TURN / Coturn cote API et affichage du bloc coturn a recopier
• Sur l’app web Millitant, les techniciens sont gérés dans admin.php?tab=technicians (promotion / retrait des comptes is_admin).

Voir aussi .env.example sur GitLab pour les noms de variables.

Tester

Une fois l'API lancee :

• index : http://localhost:9082/v1/index.php
• login admin tokens : http://localhost:9082/admin/login.php
• configuration LiveKit (apres login) : http://localhost:9082/admin/livekit.php
• configuration TURN (apres login) : http://localhost:9082/admin/turn.php
• healthcheck : http://localhost:9082/health-public.php

Exemple de test :

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

Token rapide

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

Utiliser le token :

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

Suggestions de fonctionnalites

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

Exemple de creation :

curl -X POST http://localhost:9082/v1/feature_suggestions.php \
  -H "Authorization: Bearer TON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mode hors ligne",
    "description": "Permettre la consultation locale des suggestions et du statut quand le reseau est coupe."
  }'

Reponses et reactions dans la messagerie

La messagerie privee et les groupes supportent maintenant :

• les reponses a un message via parent_id
• les reactions utilisateur sur un message
• le retour du message parent et du resume des reactions dans les listes

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

Champs supplementaires renvoyes dans les messages prives :

• parent_id
• parent_content
• parent_sender_username
• reactions_summary
• user_reaction

Champs supplementaires renvoyes dans les messages de groupe :

• parent_id
• parent_content
• parent_username
• reactions_summary
• user_reaction

Exemple de reponse a un message prive :

curl -X POST http://localhost:9082/v1/messages.php \
  -H "Authorization: Bearer TON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 34,
    "content": "Je reponds a ton message",
    "parent_id": 56
  }'

Exemple de reaction sur un message prive :

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

Exemple de reponse dans un groupe :

curl -X POST http://localhost:9082/v1/message_groups.php?path=12/messages \
  -H "Authorization: Bearer TON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Je prends celui-ci",
    "parent_id": 78
  }'

Maintenance

Si tu utilises l'installateur dedie :

./militant-api update

Sinon en Docker compose manuel :

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

Desinstallation :

./militant-api uninstall

Bots

Pour les integrations bot et les automatisations, commence par l'exemple fourni :

• Keyword Relay Bot

Lire plus

• DEMARRAGE_RAPIDE.md : test rapide et premiers appels
• DOCKER.md : details Docker et reseau
• GUIDE_SIMPLE.md : version ultra courte
• WIKI.md : documentation plus large des endpoints
• SECURITY.md : securite et modeles de protection

---