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.
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.