Militant API v1

API REST complète pour développer des clients natifs (mobile, desktop) et des bots d'automatisation pour Militant.

Prérequis

• Docker et Docker Compose
• Une instance Militant déjà installée et fonctionnelle
• IMPORTANT : L'API doit être sur le même réseau Docker que Militant pour accéder à la base de données

Installation rapide

1. Vérifier le réseau Docker de Militant

docker network ls | grep militant
Vous devriez voir : militant_militant_network

2. Télécharger et lancer

cd /tmp
wget https://gitlab.com/militant1/militant-api/-/raw/main/docker-compose.casaos.yml -O docker-compose-api.yml
docker compose -f docker-compose-api.yml up -d

3. Tester

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

Configuration

Changer le port

Éditez docker-compose-api.yml :

ports:
  - "VOTRE_PORT:80"  # Par défaut: 9082

Changer les identifiants de base de données

environment:
  - DB_HOST=militant-db
  - DB_NAME=militant
  - DB_USER=militant
  - DB_PASSWORD=VOTRE_MOT_DE_PASSE  # Même mot de passe que Militant

Partage du dossier uploads

Pour que les images uploadées via l'API soient accessibles sur le site principal, vous devez partager le dossier uploads.

Option 1 : Volume Docker externe (recommandé pour CasaOS)

Le fichier docker-compose.casaos.yml est déjà configuré pour utiliser le volume militant_militant_uploads. Aucune action nécessaire.

Option 2 : Bind mount (pour installation manuelle)

Si votre container Militant principal utilise un bind mount, trouvez d'abord le chemin :

docker inspect militant-app | grep -A 5 "uploads"

Puis modifiez docker-compose.yml :

volumes:
  - /chemin/vers/uploads:/var/www/uploads

Exemple : si le container principal monte /DATA/AppData/militant/uploads, utilisez :

volumes:
  - /DATA/AppData/militant/uploads:/var/www/uploads

Notifications Push (OneSignal)

L'API supporte désormais les notifications push via OneSignal. Pour les activer :

environment:
  - ONESIGNAL_APP_ID=VOTRE_APP_ID
  - ONESIGNAL_REST_API_KEY=VOTRE_REST_API_KEY

L'application mobile se configurera automatiquement en interrogeant le serveur.

Paramètres de Confidentialité

L'API v1 respecte désormais pleinement les paramètres de confidentialité des utilisateurs :

• Comptes Privés : Les publications, commentaires et réactions sont masqués aux non-abonnés.
• Messages : Possibilité de restreindre la réception des messages aux personnes suivies uniquement.
• Status Online : Supporté via les préférences utilisateur.

Exposer sur Internet

Pour rendre l'API accessible depuis Internet, configurez un reverse proxy Nginx avec SSL :

nginx

server {

listen 443 ssl http2;

server_name api.votre-domaine.com;

ssl_certificate /path/to/cert.pem;

ssl_certificate_key /path/to/key.pem;

location / {

proxy_pass http://localhost:9082;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

}

}

Utilisation

1. Créer un token API

Accédez au panel admin :
URL : http://VOTRE_IP:9082/admin/login.php
Connectez-vous avec vos identifiants Militant
Tous les utilisateurs peuvent créer des tokens

2. Utiliser le token

bash

curl -H "Authorization: Bearer VOTRE_TOKEN" \

http://VOTRE_IP:9082/v1/posts.php

3. Tester tous les endpoints

bash

wget https://gitlab.com/militant1/militant-api/-/raw/main/test_endpoints.sh

chmod +x test_endpoints.sh

./test_endpoints.sh http://VOTRE_IP:9082

4. Groupes (Nouveau)

L'API supporte désormais la gestion complète des contenus de groupe :

Posts de groupe :
POST /group_posts.php : Créer un post
PUT /group_posts.php : Modifier un post
DELETE /group_posts.php : Supprimer un post

Commentaires de groupe :
GET /group_comments.php : Lister les commentaires
POST /group_comments.php : Ajouter un commentaire
PUT /group_comments.php : Modifier un commentaire
DELETE /group_comments.php : Supprimer un commentaire

DELETE /group_comments.php : Supprimer un commentaire

Relations & Amis (Nouveau) :
GET /friends.php : Lister les amis et demandes en attente
POST /friends.php : Envoyer, accepter ou refuser une demande (action: send|accept|reject)
DELETE /friends.php?user_id={id} : Retirer un ami

Double Authentification (2FA) & Sécurité (Nouveau) :
GET /two_factor.php : Récupérer le statut et le secret de configuration.
POST /two_factor.php?action=enable : Activer la 2FA avec un code TOTP (génère 10 codes de secours).
DELETE /two_factor.php : Désactiver la 2FA (nécessite d'être authentifié).
Challenge Login : Si la 2FA est activée, /auth.php retournera two_factor_required: true. Vous devrez alors renvoyer la requête avec le paramètre totp contenant le code à 6 chiffres ou un code de secours.

Notifications Push (Nouveau) :
L'API intègre désormais la gestion des tokens de push pour les applications mobiles.
Les préférences de push (likes, commentaires, etc.) sont gérables via /v1/user_preferences.php.
Le serveur interagit avec OneSignal pour délivrer les notifications en temps réel.

Découverte & Suggestions (Nouveau) :
L'API propose désormais un système de suggestions intelligentes pour favoriser l'organisation :
GET /v1/discover.php?type={all|users|groups|pages}
Retourne des militants avec la même cause, les nouveaux inscrits, des groupes suggérés et des pages à suivre.
Les suggestions excluent automatiquement les personnes déjà suivies et les groupes déjà rejoints.

Traduction (Nouveau) :
L'API intègre désormais un service de traduction basé sur LibreTranslate :
POST /v1/translate.php : Traduit un texte vers une langue cible.
Paramètres : text (requis), target_lang (optionnel, défaut: 'fr').
Sécurité : Nécessite une authentification Bearer Token. Supporte la normalisation automatique des codes de langue (ex: fr-FR -> fr).

SDKs Officiels

Des bibliothèques clientes sont fournies pour faciliter l'intégration de l'API dans vos applications.

📦 SDKs Disponibles

Python SDK
Fichier: sdk/python/militant.py
Documentation: README Python
Installation: pip install requests
Couverture: 100% de l'API

Exemple:

python

from militant import MilitantClient

client = MilitantClient('https://militant.revlibertaire.com')

user = client.login('username', 'password')

Récupérer le fil d'actualité

timeline = client.get_timeline()

Créer un post

post = client.create_post('Hello from Python!')

Envoyer un message

message = client.send_message('Salut!', recipient_id=123)

Créer un groupe

group = client.create_message_group('Mon Groupe', member_ids=[456, 789])

JavaScript SDK
Fichier: sdk/javascript/militant.js
Documentation: README JavaScript
Installation: npm install axios
Couverture: 100% de l'API

Exemple:

javascript

const MilitantClient = require('./militant');

const client = new MilitantClient('https://militant.revlibertaire.com');

const user = await client.login('username', 'password');

// Récupérer le fil d'actualité

const timeline = await client.getTimeline();

// Créer un post

const post = await client.createPost('Hello from JavaScript!');

// Envoyer un message

const message = await client.sendMessage('Salut!', { recipientId: 123 });

// Créer un groupe

const group = await client.createMessageGroup('Mon Groupe', [456, 789]);

🔑 Fonctionnalités Complètes

Les deux SDKs supportent:
✅ Authentification (login, token, 2FA)
✅ Posts, commentaires, réactions, partages
✅ Utilisateurs, suivis, système d'amis
✅ Messages privés et groupes de messages
✅ Groupes, pages, événements
✅ Stories, albums, lives
✅ Modération et signalements
✅ Préférences et paramètres utilisateur
✅ Appels audio/vidéo (Flutter uniquement)
✅ Export de données

📚 Documentation

Guide complet des SDKs - Vue d'ensemble et comparaison
Documentation Python - Guide détaillé Python
Documentation JavaScript - Guide détaillé JavaScript
Liste des endpoints - Tous les endpoints disponibles

Mise à jour

bash

docker pull registry.gitlab.com/militant1/militant-api:latest

docker compose -f docker-compose-api.yml down

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

Dépannage

L'API ne démarre pas

bash

Voir les logs

docker compose -f docker-compose-api.yml logs

Vérifier que Militant fonctionne

docker ps | grep militant-db

Erreur "Database not ready"

Vérifiez que l'API est sur le même réseau Docker que Militant :

bash

docker network inspect militant_militant_network

Changer le port après installation

bash

docker compose -f docker-compose-api.yml down

nano docker-compose-api.yml # Modifier ports

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

Sécurité

Tokens hashés en SHA-256
Rate limiting : 60 req/min par IP, 100 req/h par token
Protection : SQL injection, XSS, CSRF, DoS
Logging des requêtes suspectes

Documentation

Endpoints disponibles
Installation détaillée
FAQ
Sécurité
Installation CasaOS

Licence

AGPL-3.0 - Voir LICENSE


Appels Audio/Vidéo (Flutter uniquement)

L'API supporte les appels audio/vidéo WebRTC exclusivement pour l'application mobile Flutter.

Sécurité

Header obligatoire: X-Flutter-App: militant-flutter-v1
Sans ce header, l'endpoint retourne une erreur 403
Les appels ne sont pas accessibles depuis le web

Architecture

Signaling: Via API REST (polling toutes les 2 secondes)
Média: WebRTC peer-to-peer avec serveurs STUN Google
Appels 1-to-1: Connexion directe entre 2 utilisateurs
Appels de groupe: Architecture mesh (chaque participant connecté aux autres)

Endpoints

bash

Initier un appel privé

POST /v1/calls.php?action=initiate

{

"recipient_id": 123,

"call_type": "audio|video",

"offer": "sdp_offer_string"

}

Initier un appel de groupe

POST /v1/calls.php?action=initiate

{

"group_id": 456,

"call_type": "audio|video",

"offer": "sdp_offer_string"

}

Répondre à un appel

POST /v1/calls.php?action=answer

{

"call_id": "abc123",

"answer": "sdp_answer_string"

}

Rejoindre un appel de groupe

POST /v1/calls.php?action=join

{

"call_id": "abc123",

"offer": "sdp_offer_string"

}

Échanger des ICE candidates

POST /v1/calls.php?action=ice_candidate

{

"call_id": "abc123",

"candidate": {

"candidate": "...",

"sdpMid": "...",

"sdpMLineIndex": 0

}

}

Redémarrer ICE (changement de réseau)

POST /v1/calls.php?action=ice_restart

{

"call_id": "abc123",

"offer": "new_sdp_offer"

}

Polling pour mises à jour

GET /v1/calls.php?action=poll&call_id=abc123&last_poll=2024-01-01%2012:00:00

Historique des appels

GET /v1/calls.php?action=history&page=1&per_page=50

Tables de base de données

Les migrations s'exécutent automatiquement au démarrage:

calls: Appels 1-to-1 et de groupe
call_ice_candidates: Candidats ICE pour WebRTC
group_call_participants: Participants aux appels de groupe
group_call_peer_connections: Connexions peer-to-peer mesh

ICE Restart

Support du changement de réseau (WiFi ↔ 4G/5G) pendant un appel via ICE restart. Le client Flutter détecte automatiquement les changements de connectivité et relance la négociation ICE.


📦 SDKs Officiels

Utilisez les SDKs officiels pour intégrer facilement l'API Militant dans vos applications:

Python SDK
Documentation complète
Télécharger militant.py
Installation: pip install requests

python

from militant import MilitantClient

client = MilitantClient('https://militant.revlibertaire.com')

user = client.login('username', 'password')

timeline = client.get_timeline()

post = client.create_post('Hello from Python!')

JavaScript SDK
Documentation complète
Télécharger militant.js
Installation: npm install axios

javascript

const MilitantClient = require('./militant');

const client = new MilitantClient('https://militant.revlibertaire.com');

const user = await client.login('username', 'password');

const timeline = await client.getTimeline();

const post = await client.createPost('Hello from JavaScript!');

```

Fonctionnalités des SDKs

Les deux SDKs supportent toutes les fonctionnalités de l'API:

• Authentification (login, token, 2FA)
• Posts, commentaires, réactions
• Utilisateurs, suivis, amis
• Messages privés et groupes
• Groupes, pages, événements
• Stories, albums, lives
• Modération et signalements
• Appels audio/vidéo (Flutter uniquement)
• Export de données

Voir la documentation complète des SDKs