開発者

# Welleyで作る

Welley APIを使って、クライアント、スクリプト、コミュニティ向けのツール、連携を作れます。使える操作とスキーマは、最新のSwaggerリファレンスで確認できます。

[最新のSwagger UIを開く](https://welley.social/q/swagger-ui/) [OpenAPIのJSONをダウンロードする](https://welley.social/q/openapi?format=json)

将来、Welley をオープンソースとして公開する予定です。公開日やライセンスは、まだ発表されていません。

## 公開APIへのリクエストから始める

APIはHTTPS上で動き、ほとんどの操作はJSONを受け取り、JSONを返します。公開されている情報の読み取りは、アカウントなしでも使えることがあります。

### サーバー情報を読み取る

このリクエストは、サーバーの公開メタデータを返します。サーバーのデータは変更しません。

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

### Swaggerで操作を調べる

クライアントを書く前に、パラメーター、リクエストのスキーマ、レスポンスのスキーマ、必要な権限を確認してください。

## 連携を認証する

保護された操作には、Authorizationヘッダーに有効なトークンが必要です。公式のCLIは、Bearerプレフィックスを付けてトークンを送ります。

### サーバーでの自分の有効な権限を読み取る

WELLEY\_TOKENには、普段シークレットを扱う方法で、自分の有効なトークンを設定してください。この例はデータを読み取るだけです。

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

-   連携用には、アカウント設定でパーソナルアクセストークンを作成します。
-   名前と有効期限を付けます。APIはexpiresInDays=0も受け付け、その場合は保存された有効期限のないトークンになります。
-   トークンで使えるグローバル権限、グループ権限、グループを絞り込みます。
-   許可リストを空にした項目は、現在のあなたのアクセス権の範囲だけで制限されます。トークンが、あなたにない権限を与えることはありません。
-   トークンのシークレットが表示されるのは一度だけです。作成結果を閉じる前に保存してください。
-   トークンを管理するには、アカウントのログインセッションが必要です。パーソナルアクセストークンでは、トークンの作成、一覧表示、コピー、取り消しはできません。

## 権限とスコープを確認する

認証は、誰が呼び出しているかをAPIに伝えます。その呼び出し元がどの操作を使えるかは、ロールの権限で決まります。

-   保護されたリクエストに有効な認証がない場合、APIは401を返します。
-   呼び出し元に必要な権限がない場合、APIは403を返します。
-   権限名はResource.Actionの形式です。例: GroupSettings.Manage
-   スコープ付きのWebhookや権限の操作では、scopeを省略するとサーバースコープになります。グループスコープにするには、グループのTypeIdを渡します。
-   各操作の説明を読んでください。一部のエンドポイントは、アカウントのトークンではなく、HTTP署名や別のプロトコルを使います。

## APIの分野を選ぶ

リファレンスには、ソーシャル機能、連携、サーバー管理が載っています。ここにある例は、APIのごく一部です。

### アカウントとプロフィール

プロフィールの読み取り、アカウントのアイデンティティの管理、アカウントのエクスポートや移行の操作ができます。

| メソッド | パス | 操作 | アクセス |
| --- | --- | --- | --- |
| GET | `/api/v1/users` | ユーザー名で、ローカルまたはリモートのプロフィールを読み取ります。 | 公開、またはトークンは任意 |
| POST | `/api/v1/users` | サーバーの上限まで、現在のアカウントにプロフィールを追加します。 | トークンが必要 |

### 投稿とフィード

フィードの読み取りと投稿の作成ができます。ほかの操作では、返信、投票、リアクション、下書き、保存した投稿を扱います。

| メソッド | パス | 操作 | アクセス |
| --- | --- | --- | --- |
| GET | `/api/v1/posts` | ゲストとして公開投稿を読み取れます。認証済みの場合は、あなた向けのフィードを読み取れます。 | 公開、またはトークンは任意 |
| POST | `/api/v1/posts` | 内容と公開範囲を指定して、投稿を作成します。 | トークンが必要 |

### グループとイベント

グループ、メンバーシップ、チャンネル、モデレーション、イベントを使って、コミュニティ向けのツールを作れます。

| メソッド | パス | 操作 | アクセス |
| --- | --- | --- | --- |
| POST | `/api/v1/groups` | 認証済みユーザーの権限で、グループを作成します。 | トークンが必要 |
| GET | `/api/v1/events` | 公開イベント、または認証済みユーザーが見られるイベントを一覧にします。 | 公開、またはトークンは任意 |
| POST | `/api/v1/events` | イベントを作成します。グループのイベントには、GroupEvents.Createが必要です。 | トークンが必要 |

### 会話と通知

会話ルームとそのメッセージを読み取ります。通知のコレクションを読み取り、既読かどうかを更新します。

| メソッド | パス | 操作 | アクセス |
| --- | --- | --- | --- |
| GET | `/api/v1/rooms` | 現在のユーザーのルームを一覧にします。一覧の続きを取得するには、レスポンスボディのnextCursorを使います。 | トークンが必要 |
| GET | `/api/v1/user-notifications` | 現在のユーザーの通知を一覧にします。 | トークンが必要 |

### メディア、検索、翻訳

メディアのアップロード、見られるコンテンツの検索、テキストの翻訳の依頼ができます。

| メソッド | パス | 操作 | アクセス |
| --- | --- | --- | --- |
| POST | `/api/v1/uploads` | アップロードエントリーを作成し、返されたアップロードURLにファイルの内容をPUTします。 | トークンが必要 |
| GET | `/api/v1/search` | 呼び出し元が見られるコンテンツを検索するか、対応しているURLを解決します。 | 公開、またはトークンは任意 |
| POST | `/api/v1/translate/text` | テキストを、指定した言語に翻訳します。 | トークンが必要 |

### WebhookとAIエージェント

Webhookで外部のサービスとつなげます。AIエージェントは、エージェントAPIで設定します。

| メソッド | パス | 操作 | アクセス |
| --- | --- | --- | --- |
| GET | `/api/v1/webhooks/events` | 対応しているWebhookのイベントタイプの一覧を取得します。 | トークンが必要 |
| POST | `/api/v1/webhooks` | 権限のあるサーバースコープまたはグループスコープで、Webhookを作成します。HTTP署名のシークレットが表示されるのは一度だけです。 | トークンが必要 |
| GET | `/api/v1/ai-agents` | 呼び出し元が見られるAIエージェントを一覧にします。 | トークンが必要 |

### サーバーとグループの管理

設定、通報、モデレーション、連合の制御、クォータ、デプロイの管理にAPIを使えます。

| メソッド | パス | 操作 | アクセス |
| --- | --- | --- | --- |
| GET | `/api/v1/rbac/permissions` | 現在のユーザーとスコープで有効な権限を読み取ります。 | トークンが必要 |
| GET | `/api/v1/settings` | アカウントに必要な権限があれば、プラットフォーム設定を読み取ります。 | 公開、またはトークンは任意 |

## レスポンスとメディアを扱う

ページ送りとアップロードの流れは、各操作の説明に従ってください。

-   カーソル式のフィードでは、サーバーが返すページ送りのリンクをたどってください。IDの推測でカーソルを作らないでください。
-   ルームでは、レスポンスボディに不透明なnextCursorが返されます。一覧の続きを取得するときは、同じフィルターを使い続けてください。
-   メディアをアップロードするには、アップロードエントリーを作成し、返されたURLに内容を送ります。
-   各操作のエラーレスポンスと上限を確認してください。ドキュメントに載っている操作でも、ロール、サーバーの設定、外部プロバイダーが必要な場合があります。