Programiści
Twórz z Welley
Możesz użyć API Welley, żeby tworzyć klienty, skrypty, narzędzia dla społeczności i integracje. Aktualna dokumentacja Swagger opisuje operacje i schematy, z których możesz korzystać.
Planujemy w przyszłości udostępnić Welley jako oprogramowanie open source. Nie ogłosiliśmy jeszcze daty wydania ani licencji.
Zacznij od publicznego żądania
API działa przez HTTPS, a większość operacji przyjmuje i zwraca JSON. Publiczne operacje odczytu mogą działać bez konta.
Odczytaj informacje o serwerze
To żądanie zwraca publiczne metadane o serwerze. Nie zmienia żadnych danych serwera.
curl --fail --silent --show-error "https://welley.social/api/v1/instance"Sprawdź operację w Swagger
Zanim napiszesz klienta, sprawdź parametry operacji, schemat żądania, schemat odpowiedzi i uprawnienia.
Uwierzytelnianie integracji
Chronione operacje wymagają prawidłowego tokenu w nagłówku Authorization. Nasze oficjalne CLI wysyła token z prefiksem Bearer.
Odczytaj swoje efektywne uprawnienia na serwerze
Ustaw WELLEY_TOKEN na swój ważny token, tak jak zwykle obsługujesz sekrety. Ten przykład tylko odczytuje dane.
curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions"- Dla integracji utwórz osobisty token dostępu w ustawieniach konta.
- Nadaj mu nazwę i termin ważności. API przyjmuje też expiresInDays=0 dla tokenu bez zapisanego terminu ważności.
- Ogranicz, z których uprawnień globalnych, uprawnień grupowych i grup może korzystać token.
- Jeśli zostawisz listę dozwolonych pustą, to pole jest ograniczone tylko twoim bieżącym dostępem. Token nie może dać uprawnień, których sam nie masz.
- Sekret tokenu zobaczysz tylko raz. Zapisz go, zanim zamkniesz wynik tworzenia.
- Do zarządzania tokenami potrzebujesz sesji zalogowanego konta. Osobisty token dostępu nie może tworzyć, wyświetlać, kopiować ani unieważniać tokenów.
Sprawdź uprawnienia i zakres
Uwierzytelnianie mówi API, kto wywołuje. Uprawnienia roli decydują, z których operacji ten wywołujący może korzystać.
- API zwraca 401, gdy chronione żądanie nie ma prawidłowego uwierzytelnienia.
- API zwraca 403, gdy wywołujący nie ma wymaganego uprawnienia.
- Nazwy uprawnień mają postać Resource.Action, na przykład GroupSettings.Manage.
- W operacjach webhooków i uprawnień z zakresem pomiń scope, żeby użyć zakresu serwera. Dla zakresu grupy podaj TypeId grupy.
- Przeczytaj opis każdej operacji. Niektóre endpointy używają podpisów HTTP lub innego protokołu zamiast tokenu konta.
Wybierz obszar API
Dokumentacja obejmuje funkcje społecznościowe, integracje i administrację serwerem. Przykłady tutaj to tylko niewielka część API.
Konta i profile
Odczytuj profile, zarządzaj tożsamościami konta i korzystaj z operacji eksportu lub przeniesienia konta.
| Metoda | Ścieżka | Operacja | Dostęp |
|---|---|---|---|
| GET | /api/v1/users | Odczytaj profil lokalny lub zdalny według nazwy użytkownika. | Publiczny lub opcjonalny token |
| POST | /api/v1/users | Dodaj kolejny profil do bieżącego konta, do limitu serwera. | Wymagany token |
Wpisy i aktualności
Odczytuj aktualności i twórz wpisy. Inne operacje obsługują odpowiedzi, ankiety, reakcje, wersje robocze i zapisane wpisy.
| Metoda | Ścieżka | Operacja | Dostęp |
|---|---|---|---|
| GET | /api/v1/posts | Odczytaj publiczne wpisy jako gość albo spersonalizowane aktualności po uwierzytelnieniu. | Publiczny lub opcjonalny token |
| POST | /api/v1/posts | Utwórz wpis z jego treścią i informacją, kto może go zobaczyć. | Wymagany token |
Grupy i wydarzenia
Twórz narzędzia dla społeczności z użyciem grup, członkostwa, kanałów, moderacji i wydarzeń.
| Metoda | Ścieżka | Operacja | Dostęp |
|---|---|---|---|
| POST | /api/v1/groups | Utwórz grupę, korzystając z uprawnień uwierzytelnionego użytkownika. | Wymagany token |
| GET | /api/v1/events | Wyświetl publiczne wydarzenia albo wydarzenia, które widzi uwierzytelniony użytkownik. | Publiczny lub opcjonalny token |
| POST | /api/v1/events | Utwórz wydarzenie. Wydarzenie grupy wymaga GroupEvents.Create. | Wymagany token |
Rozmowy i powiadomienia
Odczytuj pokoje rozmów i ich wiadomości. Odczytuj kolekcje powiadomień i aktualizuj informację, czy zostały przeczytane.
| Metoda | Ścieżka | Operacja | Dostęp |
|---|---|---|---|
| GET | /api/v1/rooms | Wyświetl pokoje bieżącego użytkownika. Aby kontynuować listę, użyj nextCursor z treści odpowiedzi. | Wymagany token |
| GET | /api/v1/user-notifications | Wyświetl powiadomienia bieżącego użytkownika. | Wymagany token |
Multimedia, wyszukiwanie i tłumaczenie
Przesyłaj multimedia, przeszukuj widoczne dla ciebie treści i proś o tłumaczenia tekstu.
| Metoda | Ścieżka | Operacja | Dostęp |
|---|---|---|---|
| POST | /api/v1/uploads | Utwórz rekord przesyłania, a potem wyślij zawartość pliku metodą PUT na zwrócony adres URL przesyłania. | Wymagany token |
| GET | /api/v1/search | Przeszukaj treści widoczne dla wywołującego albo rozwiąż obsługiwane adresy URL. | Publiczny lub opcjonalny token |
| POST | /api/v1/translate/text | Przetłumacz tekst na żądany język. | Wymagany token |
Webhooki i agenci AI
Połącz zewnętrzne usługi przez webhooki. Konfiguruj agentów AI przez API agentów.
| Metoda | Ścieżka | Operacja | Dostęp |
|---|---|---|---|
| GET | /api/v1/webhooks/events | Pobierz listę obsługiwanych typów zdarzeń webhooków. | Wymagany token |
| POST | /api/v1/webhooks | Utwórz webhook w zakresie serwera lub grupy, do którego masz uprawnienia. Sekret podpisu HTTP jest pokazywany tylko raz. | Wymagany token |
| GET | /api/v1/ai-agents | Wyświetl agentów AI, których widzi wywołujący. | Wymagany token |
Administracja serwerem i grupami
Używaj API do ustawień, zgłoszeń, moderacji, kontroli federacji, limitów i administrowania wdrożeniem.
| Metoda | Ścieżka | Operacja | Dostęp |
|---|---|---|---|
| GET | /api/v1/rbac/permissions | Odczytaj efektywne uprawnienia bieżącego użytkownika w danym zakresie. | Wymagany token |
| GET | /api/v1/settings | Odczytaj ustawienia platformy, jeśli konto ma wymagane uprawnienia. | Publiczny lub opcjonalny token |
Obsługa odpowiedzi i multimediów
W każdej operacji stosuj jej własny sposób stronicowania i przesyłania plików.
- W aktualnościach z kursorem korzystaj z linków stronicowania zwracanych przez serwer. Nie buduj kursorów na podstawie domysłów o identyfikatorach.
- Pokoje zwracają nieprzejrzysty nextCursor w treści odpowiedzi. Gdy kontynuujesz listę, zachowaj te same filtry.
- Aby przesłać multimedia, utwórz rekord przesyłania, a potem wyślij zawartość na zwrócony adres URL.
- Sprawdź odpowiedzi błędów i limity każdej operacji. Nawet udokumentowana operacja może wymagać roli, konfiguracji serwera lub zewnętrznego dostawcy.