Sviluppatori # Costruisci con Welley Puoi usare l'API di Welley per creare client, script, strumenti per la community e integrazioni. Il riferimento Swagger online descrive le operazioni e gli schemi che puoi usare. [Apri Swagger UI online](https://welley.social/q/swagger-ui/) [Scarica il JSON OpenAPI](https://welley.social/q/openapi?format=json) In futuro prevediamo di rilasciare Welley come open source. Per ora non sono state annunciate né una data di rilascio né una licenza. ## Inizia con una richiesta pubblica L'API funziona su HTTPS e la maggior parte delle operazioni accetta e restituisce JSON. Le operazioni di lettura pubbliche possono funzionare senza un account. ### Leggi le informazioni sul server Questa richiesta restituisce metadati pubblici sul server. Non modifica nessun dato del server. ``` curl --fail --silent --show-error "https://welley.social/api/v1/instance" ``` ### Cerca l'operazione in Swagger Prima di scrivere un client, controlla i parametri, lo schema della richiesta, lo schema della risposta e i permessi. ## Autentica un'integrazione Le operazioni protette richiedono un token valido nell'header Authorization. La nostra CLI ufficiale invia il token con il prefisso Bearer. ### Leggi i tuoi permessi effettivi sul server Imposta WELLEY\_TOKEN con un tuo token valido, nel modo in cui gestisci di solito i segreti. Questo esempio legge soltanto dati. ``` curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions" ``` - Per un'integrazione, crea un token di accesso personale nelle impostazioni del tuo account. - Dagli un nome e una scadenza. L'API accetta anche expiresInDays=0 per un token senza scadenza memorizzata. - Limita quali permessi globali, permessi di gruppo e gruppi il token può usare. - Se lasci vuota una lista di elementi consentiti, quel campo è limitato solo dal tuo accesso attuale. Un token non può dare diritti che tu non hai. - Vedrai il segreto del token una sola volta. Salvalo prima di chiudere il risultato della creazione. - Per gestire i token ti serve una sessione di accesso all'account. Un token di accesso personale non può creare, elencare, copiare o revocare token. ## Controlla permessi e ambito L'autenticazione dice all'API chi sta chiamando. I permessi del ruolo decidono quali operazioni quel chiamante può usare. - L'API restituisce 401 quando una richiesta protetta non ha un'autenticazione valida. - L'API restituisce 403 quando il chiamante non ha un permesso richiesto. - I nomi dei permessi seguono il formato Resource.Action, per esempio GroupSettings.Manage. - Per le operazioni su webhook e permessi con ambito, ometti scope per usare l'ambito del server. Per l'ambito di un gruppo, passa il TypeId del gruppo. - Leggi la descrizione di ogni operazione. Alcuni endpoint usano firme HTTP o un altro protocollo invece di un token dell'account. ## Scegli un'area dell'API Il riferimento copre funzioni social, integrazioni e amministrazione del server. Gli esempi qui sono solo una piccola parte dell'API. ### Account e profili Leggi i profili, gestisci le identità dell'account e usa le operazioni di esportazione o di spostamento dell'account. | Metodo | Percorso | Operazione | Accesso | | --- | --- | --- | --- | | GET | `/api/v1/users` | Leggi un profilo locale o remoto tramite il nome utente. | Pubblico o token facoltativo | | POST | `/api/v1/users` | Aggiungi un altro profilo all'account attuale, fino al limite del server. | Token richiesto | ### Post e feed Leggi i feed e crea post. Altre operazioni gestiscono risposte, sondaggi, reazioni, bozze e post salvati. | Metodo | Percorso | Operazione | Accesso | | --- | --- | --- | --- | | GET | `/api/v1/posts` | Leggi i post pubblici come ospite, oppure un feed personalizzato quando sei autenticato. | Pubblico o token facoltativo | | POST | `/api/v1/posts` | Crea un post indicando il contenuto e chi può vederlo. | Token richiesto | ### Gruppi ed eventi Crea strumenti per la community con gruppi, appartenenza, canali, moderazione ed eventi. | Metodo | Percorso | Operazione | Accesso | | --- | --- | --- | --- | | POST | `/api/v1/groups` | Crea un gruppo, usando i permessi dell'utente autenticato. | Token richiesto | | GET | `/api/v1/events` | Elenca gli eventi pubblici o gli eventi che l'utente autenticato può vedere. | Pubblico o token facoltativo | | POST | `/api/v1/events` | Crea un evento. Un evento di gruppo richiede GroupEvents.Create. | Token richiesto | ### Conversazioni e notifiche Leggi le stanze di conversazione e i loro messaggi. Leggi le raccolte di notifiche e aggiorna il loro stato di lettura. | Metodo | Percorso | Operazione | Accesso | | --- | --- | --- | --- | | GET | `/api/v1/rooms` | Elenca le stanze dell'utente attuale. Per continuare l'elenco, usa nextCursor dal corpo della risposta. | Token richiesto | | GET | `/api/v1/user-notifications` | Elenca le notifiche dell'utente attuale. | Token richiesto | ### Media, ricerca e traduzione Carica media, cerca tra i contenuti che puoi vedere e chiedi traduzioni di testo. | Metodo | Percorso | Operazione | Accesso | | --- | --- | --- | --- | | POST | `/api/v1/uploads` | Crea una voce di caricamento, poi invia con PUT il contenuto del file all'URL di caricamento che ricevi. | Token richiesto | | GET | `/api/v1/search` | Cerca tra i contenuti che il chiamante può vedere, oppure risolvi gli URL supportati. | Pubblico o token facoltativo | | POST | `/api/v1/translate/text` | Traduci il testo nella lingua richiesta. | Token richiesto | ### Webhook e agenti IA Collega servizi esterni con i webhook. Configura gli agenti IA tramite le API per gli agenti. | Metodo | Percorso | Operazione | Accesso | | --- | --- | --- | --- | | GET | `/api/v1/webhooks/events` | Ottieni l'elenco dei tipi di evento webhook supportati. | Token richiesto | | POST | `/api/v1/webhooks` | Crea un webhook in un ambito di server o di gruppo per cui hai il permesso. Il segreto di firma HTTP viene mostrato una sola volta. | Token richiesto | | GET | `/api/v1/ai-agents` | Elenca gli agenti IA che il chiamante può vedere. | Token richiesto | ### Amministrazione di server e gruppi Usa l'API per impostazioni, segnalazioni, moderazione, controlli della federazione, quote e amministrazione del deployment. | Metodo | Percorso | Operazione | Accesso | | --- | --- | --- | --- | | GET | `/api/v1/rbac/permissions` | Leggi i permessi effettivi per l'utente e l'ambito attuali. | Token richiesto | | GET | `/api/v1/settings` | Leggi le impostazioni della piattaforma, se l'account ha i permessi necessari. | Pubblico o token facoltativo | ## Gestisci risposte e media Segui la paginazione e il flusso di caricamento propri di ogni operazione. - Per i feed a cursore, segui i link di paginazione che il server restituisce. Non costruire cursori ipotizzando gli ID. - Le stanze restituiscono un nextCursor opaco nel corpo della risposta. Quando continui l'elenco, mantieni gli stessi filtri. - Per caricare contenuti multimediali, crea una voce di caricamento, poi invia il contenuto all'URL che ricevi. - Controlla le risposte di errore e i limiti di ogni operazione. Anche un'operazione documentata può richiedere un ruolo, una configurazione del server o un provider esterno.