Développeurs # Créez avec Welley Vous pouvez utiliser l'API de Welley pour créer des clients, des scripts, des outils de communauté et des intégrations. La référence Swagger en ligne décrit les opérations et les schémas disponibles. [Ouvrir Swagger UI en ligne](https://welley.social/q/swagger-ui/) [Télécharger le JSON OpenAPI](https://welley.social/q/openapi?format=json) Nous prévoyons de publier Welley en open source à l'avenir. Aucune date de sortie ni licence n'est encore annoncée. ## Commencez par une requête publique L'API fonctionne en HTTPS, et la plupart des opérations reçoivent et renvoient du JSON. Les opérations de lecture publiques peuvent fonctionner sans compte. ### Lire les informations du serveur Cette requête renvoie des métadonnées publiques sur le serveur. Elle ne modifie aucune donnée du serveur. ``` curl --fail --silent --show-error "https://welley.social/api/v1/instance" ``` ### Retrouvez l'opération dans Swagger Avant d'écrire un client, vérifiez les paramètres de l'opération, son schéma de requête, son schéma de réponse et ses autorisations. ## Authentifier une intégration Les opérations protégées demandent un jeton valide dans l'en-tête Authorization. Notre CLI officielle envoie le jeton avec le préfixe Bearer. ### Lire vos autorisations effectives sur le serveur Définissez WELLEY\_TOKEN avec votre propre jeton valide, comme vous le faites d'habitude pour les secrets. Cet exemple ne fait que lire des données. ``` curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions" ``` - Pour une intégration, créez un jeton d'accès personnel dans les paramètres de votre compte. - Donnez-lui un nom et une date d'expiration. L'API accepte aussi expiresInDays=0 pour un jeton sans expiration enregistrée. - Limitez les autorisations globales, les autorisations de groupe et les groupes que le jeton peut utiliser. - Si vous laissez une liste d'autorisations vide, ce champ n'est limité que par votre accès actuel. Un jeton ne peut pas donner des droits que vous n'avez pas. - Vous ne verrez le secret du jeton qu'une seule fois. Enregistrez-le avant de fermer le résultat de la création. - Pour gérer les jetons, vous avez besoin d'une session de connexion à un compte. Un jeton d'accès personnel ne peut pas créer, lister, copier ni révoquer de jetons. ## Vérifier les autorisations et la portée L'authentification indique à l'API qui appelle. Les autorisations du rôle décident quelles opérations cet appelant peut utiliser. - L'API renvoie 401 quand une requête protégée n'a pas d'authentification valide. - L'API renvoie 403 quand l'appelant n'a pas l'une des autorisations requises. - Les noms d'autorisation suivent le format Resource.Action, par exemple GroupSettings.Manage. - Pour les opérations de webhook et d'autorisation avec portée, omettez scope pour utiliser la portée du serveur. Pour la portée d'un groupe, passez le TypeId du groupe. - Lisez la description de chaque opération. Certains points d'accès utilisent des signatures HTTP ou un autre protocole au lieu d'un jeton de compte. ## Choisissez un domaine de l'API La référence couvre les fonctions sociales, les intégrations et l'administration du serveur. Les exemples ici ne sont qu'une petite partie de l'API. ### Comptes et profils Lisez des profils, gérez les identités d'un compte et utilisez les opérations d'exportation ou de transfert de compte. | Méthode | Chemin | Opération | Accès | | --- | --- | --- | --- | | GET | `/api/v1/users` | Lisez un profil local ou distant à partir de son nom d'utilisateur. | Public ou jeton facultatif | | POST | `/api/v1/users` | Ajoutez un autre profil au compte actuel, dans la limite du serveur. | Jeton requis | ### Publications et fils d'actualité Lisez des fils d'actualité et créez des publications. D'autres opérations gèrent les réponses, les sondages, les réactions, les brouillons et les publications enregistrées. | Méthode | Chemin | Opération | Accès | | --- | --- | --- | --- | | GET | `/api/v1/posts` | Lisez les publications publiques en tant qu'invité, ou un fil d'actualité personnalisé quand vous êtes authentifié. | Public ou jeton facultatif | | POST | `/api/v1/posts` | Créez une publication avec son contenu et les personnes qui peuvent la voir. | Jeton requis | ### Groupes et événements Créez des outils de communauté avec les groupes, l'adhésion, les chaînes, la modération et les événements. | Méthode | Chemin | Opération | Accès | | --- | --- | --- | --- | | POST | `/api/v1/groups` | Créez un groupe, avec les autorisations de l'utilisateur authentifié. | Jeton requis | | GET | `/api/v1/events` | Listez les événements publics ou ceux que l'utilisateur authentifié peut voir. | Public ou jeton facultatif | | POST | `/api/v1/events` | Créez un événement. Un événement de groupe demande GroupEvents.Create. | Jeton requis | ### Conversations et notifications Lisez les salons de conversation et leurs messages. Lisez les collections de notifications et mettez à jour leur état lu ou non lu. | Méthode | Chemin | Opération | Accès | | --- | --- | --- | --- | | GET | `/api/v1/rooms` | Listez les salons de l'utilisateur actuel. Pour continuer la liste, utilisez nextCursor dans le corps de la réponse. | Jeton requis | | GET | `/api/v1/user-notifications` | Listez les notifications de l'utilisateur actuel. | Jeton requis | ### Médias, recherche et traduction Téléversez des médias, recherchez dans le contenu que vous pouvez voir et demandez des traductions de texte. | Méthode | Chemin | Opération | Accès | | --- | --- | --- | --- | | POST | `/api/v1/uploads` | Créez une entrée de téléversement, puis envoyez le contenu du fichier avec PUT à l'URL de téléversement renvoyée. | Jeton requis | | GET | `/api/v1/search` | Recherchez dans le contenu que l'appelant peut voir, ou résolvez des URL prises en charge. | Public ou jeton facultatif | | POST | `/api/v1/translate/text` | Traduisez un texte dans la langue demandée. | Jeton requis | ### Webhooks et agents IA Connectez des services externes avec des webhooks. Configurez des agents IA avec les API d'agents. | Méthode | Chemin | Opération | Accès | | --- | --- | --- | --- | | GET | `/api/v1/webhooks/events` | Obtenez la liste des types d'événements webhook pris en charge. | Jeton requis | | POST | `/api/v1/webhooks` | Créez un webhook dans une portée serveur ou groupe pour laquelle vous avez l'autorisation. Le secret de signature HTTP n'est affiché qu'une seule fois. | Jeton requis | | GET | `/api/v1/ai-agents` | Listez les agents IA que l'appelant peut voir. | Jeton requis | ### Administration du serveur et des groupes Utilisez l'API pour les paramètres, les signalements, la modération, les contrôles de fédération, les quotas et l'administration du déploiement. | Méthode | Chemin | Opération | Accès | | --- | --- | --- | --- | | GET | `/api/v1/rbac/permissions` | Lisez les autorisations effectives pour l'utilisateur actuel et la portée. | Jeton requis | | GET | `/api/v1/settings` | Lisez les paramètres de la plateforme, si le compte a les autorisations requises. | Public ou jeton facultatif | ## Gérer les réponses et les médias Suivez la pagination et le processus de téléversement propres à chaque opération. - Pour les fils d'actualité à curseur, suivez les liens de pagination que renvoie le serveur. Ne construisez pas de curseurs en devinant les ID. - Les salons renvoient un nextCursor opaque dans le corps de la réponse. Quand vous continuez la liste, gardez les mêmes filtres. - Pour téléverser un média, créez une entrée de téléversement, puis envoyez le contenu à l'URL renvoyée. - Vérifiez les réponses d'erreur et les limites de chaque opération. Même une opération documentée peut demander un rôle, une configuration du serveur ou un fournisseur externe.