Vývojáři

# Vyvíjejte s Welley

Pomocí Welley API můžete vytvářet klienty, skripty, nástroje pro komunity a integrace. Živá reference Swagger popisuje operace a schémata, která můžete použít.

[Otevřít živé Swagger UI](https://welley.social/q/swagger-ui/) [Stáhnout OpenAPI JSON](https://welley.social/q/openapi?format=json)

V budoucnu plánujeme vydat Welley jako open source. Datum vydání ani licence zatím nebyly oznámeny.

## Začněte veřejným požadavkem

API funguje přes HTTPS a většina operací přijímá i vrací JSON. Veřejné operace čtení mohou fungovat i bez účtu.

### Zjištění informací o serveru

Tento požadavek vrací veřejná metadata o serveru. Žádná data na serveru nemění.

```
curl --fail --silent --show-error "https://welley.social/api/v1/instance"
```

### Najděte operaci ve Swaggeru

Než napíšete klienta, zkontrolujte parametry operace, schéma požadavku, schéma odpovědi a oprávnění.

## Ověření integrace

Chráněné operace potřebují platný token v hlavičce Authorization. Náš oficiální CLI posílá token s prefixem Bearer.

### Přečtěte si svá platná oprávnění na serveru

Nastavte WELLEY\_TOKEN na svůj vlastní platný token tak, jak obvykle zacházíte s tajnými údaji. Tento příklad data pouze čte.

```
curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions"
```

-   Pro integraci vytvořte osobní přístupový token v nastavení svého účtu.
-   Dejte mu název a dobu platnosti. API přijímá také expiresInDays=0 pro token bez uložené doby platnosti.
-   Omezte, která globální oprávnění, oprávnění ve skupinách a které skupiny může token používat.
-   Pokud necháte seznam povolených prázdný, je toto pole omezeno jen vaším aktuálním přístupem. Token nemůže udělit práva, která sami nemáte.
-   Tajný klíč tokenu uvidíte jen jednou. Uložte si ho, než zavřete výsledek vytvoření.
-   Ke správě tokenů potřebujete přihlášenou relaci k účtu. Osobní přístupový token nemůže tokeny vytvářet, vypisovat, kopírovat ani rušit.

## Kontrola oprávnění a rozsahu

Ověření říká API, kdo volá. Oprávnění rolí určují, které operace může tento volající používat.

-   API vrací 401, když chráněný požadavek nemá platné ověření.
-   API vrací 403, když volající nemá požadované oprávnění.
-   Názvy oprávnění mají tvar Resource.Action, například GroupSettings.Manage.
-   U operací s webhooky a oprávněními, které pracují s rozsahem, vynechte scope, pokud chcete použít rozsah serveru. Pro rozsah skupiny předejte TypeId skupiny.
-   Přečtěte si popis každé operace. Některé endpointy místo tokenu účtu používají podpisy HTTP nebo jiný protokol.

## Vyberte oblast API

Reference pokrývá sociální funkce, integrace a správu serveru. Uvedené příklady pokrývají jen malou část API.

### Účty a profily

Čtěte profily, spravujte identity účtu a používejte operace exportu nebo přesunu účtu.

| Metoda | Cesta | Operace | Přístup |
| --- | --- | --- | --- |
| GET | `/api/v1/users` | Přečtěte místní nebo vzdálený profil podle uživatelského jména. | Veřejné nebo s volitelným tokenem |
| POST | `/api/v1/users` | Přidejte k aktuálnímu účtu další profil, až do limitu serveru. | Vyžaduje token |

### Příspěvky a feedy

Čtěte feedy a vytvářejte příspěvky. Další operace se týkají odpovědí, anket, reakcí, konceptů a uložených příspěvků.

| Metoda | Cesta | Operace | Přístup |
| --- | --- | --- | --- |
| GET | `/api/v1/posts` | Čtěte veřejné příspěvky jako host, nebo personalizovaný feed, když jste ověřeni. | Veřejné nebo s volitelným tokenem |
| POST | `/api/v1/posts` | Vytvořte příspěvek s jeho obsahem a nastavením, kdo ho uvidí. | Vyžaduje token |

### Skupiny a události

Vytvářejte nástroje pro komunity se skupinami, členstvím, kanály, moderací a událostmi.

| Metoda | Cesta | Operace | Přístup |
| --- | --- | --- | --- |
| POST | `/api/v1/groups` | Vytvořte skupinu s oprávněními ověřeného uživatele. | Vyžaduje token |
| GET | `/api/v1/events` | Vypište veřejné události nebo události, které může ověřený uživatel vidět. | Veřejné nebo s volitelným tokenem |
| POST | `/api/v1/events` | Vytvořte událost. Událost skupiny vyžaduje GroupEvents.Create. | Vyžaduje token |

### Konverzace a oznámení

Čtěte konverzační místnosti a jejich zprávy. Čtěte kolekce oznámení a měňte jejich stav přečtení.

| Metoda | Cesta | Operace | Přístup |
| --- | --- | --- | --- |
| GET | `/api/v1/rooms` | Vypište místnosti aktuálního uživatele. Chcete-li ve výpisu pokračovat, použijte nextCursor z těla odpovědi. | Vyžaduje token |
| GET | `/api/v1/user-notifications` | Vypište oznámení aktuálního uživatele. | Vyžaduje token |

### Média, vyhledávání a překlad

Nahrávejte média, hledejte v obsahu, který můžete vidět, a žádejte o překlady textu.

| Metoda | Cesta | Operace | Přístup |
| --- | --- | --- | --- |
| POST | `/api/v1/uploads` | Vytvořte záznam o nahrávání a pak odešlete obsah souboru metodou PUT na adresu pro nahrání, kterou vrátí. | Vyžaduje token |
| GET | `/api/v1/search` | Hledejte v obsahu, který může volající vidět, nebo rozpoznejte podporované adresy URL. | Veřejné nebo s volitelným tokenem |
| POST | `/api/v1/translate/text` | Přeložte text do požadovaného jazyka. | Vyžaduje token |

### Webhooky a AI agenti

Propojte externí služby pomocí webhooků. AI agenty nastavíte přes API agentů.

| Metoda | Cesta | Operace | Přístup |
| --- | --- | --- | --- |
| GET | `/api/v1/webhooks/events` | Získejte seznam podporovaných typů událostí webhooků. | Vyžaduje token |
| POST | `/api/v1/webhooks` | Vytvořte webhook v rozsahu serveru nebo skupiny, pro který máte oprávnění. Tajný klíč pro podepisování HTTP se zobrazí jen jednou. | Vyžaduje token |
| GET | `/api/v1/ai-agents` | Vypište AI agenty, které může volající vidět. | Vyžaduje token |

### Správa serveru a skupin

Přes API můžete spravovat nastavení, hlášení, moderaci, ovládání federace, kvóty a nasazení.

| Metoda | Cesta | Operace | Přístup |
| --- | --- | --- | --- |
| GET | `/api/v1/rbac/permissions` | Přečtěte platná oprávnění aktuálního uživatele v daném rozsahu. | Vyžaduje token |
| GET | `/api/v1/settings` | Přečtěte nastavení platformy, pokud má účet potřebná oprávnění. | Veřejné nebo s volitelným tokenem |

## Práce s odpověďmi a médii

Řiďte se stránkováním a postupem nahrávání, které má každá operace.

-   U feedů s kurzorem používejte odkazy pro stránkování, které server vrací. Kurzory nevytvářejte z odhadů ID.
-   Výpis místností vrací v těle odpovědi neprůhledný nextCursor. Když ve výpisu pokračujete, ponechte stejné filtry.
-   Při nahrávání médií vytvořte záznam o nahrávání a pak odešlete obsah na adresu, kterou vrátí.
-   Zkontrolujte chybové odpovědi a limity každé operace. I zdokumentovaná operace může vyžadovat roli, konfiguraci serveru nebo externího poskytovatele.