Klara kaj deplojebla API-dokumentaro

API por movaj klientoj, labortablaj programoj kaj aŭtomatigo ĉirkaŭ Militant-instanco.

Instalilo · Docker · Rapida komenco · Vikio · Sekureco

Instalado

La plej simpla metodo estas uzi la dediĉitan instalilon:

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

La skripto:

• konektas al la ĝusta Docker-reto
• ligas la API al la ĉefa datumbazo
• administras kundividon de uploads
• generas .env.api
• generas docker-compose.api.yml

Utilaj komandoj:

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

Dediĉita gvidilo: https://gitlab.com/militant1/api-installer

Antaupostuloj

• la ĉefa Militant-aplikaĵo jam devas funkcii
• la API devas aliĝi al la sama Docker-reto
• la Militant-datumbazo devas esti atingebla
• se vi volas la samajn dosierojn, kundividu ankaŭ uploads

Fediverse (ActivityPub)

La API nun provizas kompletan poŝtelefonan Fediversan interfacon per v1/fediverse.php: loka profilo, foraj abonantoj, fora sekvatlisto, serĉo de adresoj @uzanto@instanco, solvado de foraj profiloj, agoj por sekvi/malsekvi kaj sinkronigita fluo de foraj afiŝoj. Ĝi ankaŭ aŭtomate ekigas ActivityPub-dissendadon dum kreado de novaj afiŝoj uzante RSA HTTP-Signaturojn.

Vidu dokumentadon de Retejopunkto

Mana Docker

Se vi preferas administri Compose permane:

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

Ĉefaj variabloj:

• DB_HOST aŭ API_DB_HOST: MySQL-gastiganto de la Militant-instanco
• DB_NAME aŭ API_DB_NAME: ĉefa datumbazo
• DB_USER / DB_PASSWORD: SQL-identigiloj
• MAIN_APP_HOST: interna retadreso de la ĉefa aplikaĵo en la Docker-reto, ekzemple http://militant-web:80
• API_UPLOADS_PATH: interna vojo por dosieroj, kutime /var/www/uploads
• API_CORS_ORIGINS: * aŭ permesitaj domajno(j)
• API_REQUIRE_HTTPS: true por publika HTTPS-produktado

LiveKit (lives video)

Por generi LiveKit-tokenojn servilflanke (POST /v1/lives.php?path=token), agordu sekretojn:

• Mediavariabloj (rekomendata en produktado): LIVEKIT_URL (wss://...), LIVEKIT_API_KEY, LIVEKIT_API_SECRET
• Aux loka dosiero ignorata de git: config/livekit.local.php (generita el la reta panelo)
• La detaloj de rekta elsendo (GET /v1/lives.php?path={id}) povas inkluzivi background_image, kiun la kreinto povas gxisdatigi per PUT /v1/lives.php?path={id}/background.

WebRTC / TURN (privataj vokoj, grupoj, 4G/5G)

Por fidindaj poŝtelefonaj vokoj, speciale en 4G/5G, agordu TURN-servilon:

• Mediavariabloj: WEBRTC_TURN_URLS, WEBRTC_TURN_AUTH_SECRET, WEBRTC_TURN_TTL, WEBRTC_TURN_REALM
• Aux loka dosiero ignorata de git: config/turn.local.php (generita el la reta panelo)
• GET /v1/settings.php redonas stun_servers, turn_servers kaj webrtc_ice_servers
• se WEBRTC_TURN_AUTH_SECRET estas agordita, la API generas provizorajn HMAC TURN-kredencialojn (rekomendata reĝimo, kongrua kun coturn use-auth-secret)

Reta panelo (post ensaluto per Militant-uzantkonto):

• .../admin/login.php kaj poste .../admin/tokens.php
• .../admin/livekit.php: enigi LiveKit-kredencialojn (konta pasvorto necesas por konservi) — nur Militant-teknikistoj (same kiel la retejo: users.is_admin = 1; rezervo: is_technician aux LIVEKIT_TECHNICIAN_USER_IDS)
• .../admin/turn.php: enigi TURN / Coturn-agordon por la API kaj montri la kopiendajn coturn liniojn
• Ce la reteja aplikaĵo Militant, teknikistojn oni administras en admin.php?tab=technicians (altigo / forigo de is_admin).

Vidu ankau .env.example ĉe GitLab por variablonomoj.

Testi

Post kiam la API funkcias:

• indekso: http://localhost:9082/v1/index.php
• administra ensaluto por tokenoj: http://localhost:9082/admin/login.php
• LiveKit-agordo (post ensaluto): http://localhost:9082/admin/livekit.php
• TURN-agordo (post ensaluto): http://localhost:9082/admin/turn.php
• healthcheck: http://localhost:9082/health-public.php

Ekzemplo:

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

Rapida tokeno

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

Uzi la tokenon:

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

Sugestoj pri funkcioj

Disponeblaj finpunktoj:

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

Ekzemplo de kreado:

curl -X POST http://localhost:9082/v1/feature_suggestions.php \
  -H "Authorization: Bearer VIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senkonekta reĝimo",
    "description": "Ebligi lokan konsulton de sugestoj kaj stato kiam la reto ne estas disponebla."
  }'

Respondoj kaj reagoj en mesagxado

Privata mesagxado kaj mesagxgrupoj nun subtenas:

• respondi al mesagxo per parent_id
• uzantajn reagojn sur mesagxoj
• redoni la gepatran mesagxon kaj reagresumon en la listoj

Disponeblaj finpunktoj:

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

Pliaj kampoj resenditaj por privataj mesagxoj:

• parent_id
• parent_content
• parent_sender_username
• reactions_summary
• user_reaction

Pliaj kampoj resenditaj por grupaj mesagxoj:

• parent_id
• parent_content
• parent_username
• reactions_summary
• user_reaction

Ekzemplo de respondo al privata mesagxo:

curl -X POST http://localhost:9082/v1/messages.php \
  -H "Authorization: Bearer VIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 34,
    "content": "Mi respondas al via mesagxo",
    "parent_id": 56
  }'

Ekzemplo de reago sur privata mesagxo:

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

Ekzemplo de respondo en grupo:

curl -X POST http://localhost:9082/v1/message_groups.php?path=12/messages \
  -H "Authorization: Bearer VIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Mi prizorgos cxi tiun",
    "parent_id": 78
  }'

Prizorgado

Se vi uzas la dediĉitan instalilon:

./militant-api update

Alie per mana Docker Compose:

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

Malinstalo:

./militant-api uninstall

Botoj

Por botaj integriĝoj kaj auxtomatigoj, komencu per la enmetita ekzemplo:

• Keyword Relay Bot

Legi pli

• DEMARRAGE_RAPIDE.md: unua testo kaj unuaj alvokoj
• DOCKER.md: detaloj pri Docker kaj reto
• GUIDE_SIMPLE.md: tre mallonga versio
• WIKI.md: pli vasta dokumentado pri finpunktoj
• SECURITY.md: sekureco kaj produktaj notoj

---