Contents
Bluesky API開発入門ガイド：Webアプリケーション開発者向け完全ガイド
本ガイドは、Node.js環境でBluesky APIを活用するWebアプリケーション開発者向けの入門資料です。
公式SDK「@atproto/api」と連携しながら、認証フローから投稿・タイムライン取得までの基本運用を体系的に解説します。
対象読者はJavaScript/TypeScript環境でのWebサービス開発経験を持つ中級者〜上級者を想定しています。
開発者アカウント取得と初期設定
Bluesky APIの利用には、公式で提供される開発者アカウントが必要です。
本セクションでは、アプリケーション登録から環境構築までの一連の手順を明確に示します。
アカウント登録とアプリケーション登録の流れ
- 公式サイトアクセス：https://developer.bsky.app へ移動し「新規登録」ボタンをクリック
- 個人情報入力：メールアドレス・パスワードを設定し、用途（例: Webアプリケーション開発）を記載
- 確認コード取得：登録用メールに送信された確認コードを入力して完了
注意: アプリケーション登録時にClient IDとClient Secretが発行されます。これらは本番環境でも漏洩しないよう厳重に管理してください。
OAuth2認証フローの詳細
Bluesky APIはOAuth 2.0プロトコルを採用しています。
クライアント資格情報フロー（Client Credentials Flow）によるトークン取得が主な実装方法です。
クライアント資格情報フローの実装手順
|
1 2 3 4 5 6 7 8 9 |
const { createClient } = require("@atproto/api"); // 環境変数からシークレット値を読み込み const client = await createClient({ service: "https://bsky.social", clientId: process.env.CLIENT_ID, clientSecret: process.env.CLIENT_SECRET, }); |
重要: 上記コードでは
createClient()が自動でアクセストークンを取得しない点に注意してください。
実際にはclient.auth()メソッドを明示的に呼び出す必要があります（公式ドキュメント参照）。
アクセストークン管理のベストプラクティス
| 項目 | 内容 | 補足 |
|---|---|---|
| 有効期間 | 通常1時間 | サーバー設定に依存 |
| リフレッシュトークン | 必要なら自動で取得可能 | client.auth()で再取得可能 |
| エラー処理 | 401 Unauthorized時に再認証 |
リトライロジックを実装推奨 |
Node.js SDK導入とプロジェクト構成
公式SDK「@atproto/api」を使用するための環境設定と基本的な構成方法です。
SDKインストール手順と初期化例
|
1 2 |
npm install @atproto/api |
.envファイルの記述例
|
1 2 3 |
CLIENT_ID=your_client_id CLIENT_SECRET=your_client_secret |
index.jsの基本構成
|
1 2 3 4 5 6 7 8 9 10 11 12 |
const { createClient } = require("@atproto/api"); (async () => { const client = await createClient({ service: "https://bsky.social", clientId: process.env.CLIENT_ID, clientSecret: process.env.CLIENT_SECRET, }); // API呼び出しの例（後述） })(); |
注意: SDK導入時はプロジェクトルートに
package.jsonが存在することを確認してください。
テキスト投稿APIの実装
投稿機能は/xrpc/com.atproto.repo.createRecordエンドポイントを使用します。
投稿内容の構造と成功時の応答例を解説します。
投稿リクエストパラメータの定義
- repo：投稿者のアカウントID（
did:plc:xyz123形式） - collection：コレクション名（例:
app.bsky.feed.post） - record：投稿内容（テキスト、ハッシュタグなど）
成功時のレスポンス構造
|
1 2 3 4 5 |
{ "uri": "at://did:plc:xyz123/app.bsky.feed.post/abc456", "cid": "bafyreif7x9p8a9qkz5l..." } |
URIは投稿の永続的な識別子、CIDは内容のハッシュ値です。
タイムライン取得APIの実装
タイムラインを取得するには/xrpc/com.atproto.sync.getTimelineエンドポイントを使用します。
取得されたデータの解析方法も解説します。
API呼び出し例とパラメータ指定
|
1 2 3 4 |
const timeline = await client.api("/xrpc/com.atproto.sync.getTimeline", { limit: 20, }); |
- limit：取得する投稿数（最大100件）
- デフォルトは
20件と設定推奨
投稿データの構造解析
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "timeline": [ { "post": { "uri": "at://did:plc:xyz123/app.bsky.feed.post/abc456", "text": "サンプル投稿です" } }, // ... ] } |
timeline配列からuri（投稿ID）とtext（本文）を抽出して処理します。
エラーハンドリングのベストプラクティス
API呼び出し時の異常対応はアプリケーションの信頼性に直結します。
主なエラー種類とそれらの処理方法を確認してください。
代表的なエラーコードと対応策
| エラーコード | 説明 | 対処方法 |
|---|---|---|
| 401 Unauthorized | 認証失敗 | アクセストークンを再取得する（client.auth()実行） |
| 403 Forbidden | 操作権限なし | ユーザーIDやトークンの有効性確認 |
| 500 Internal Server Error | サーバーエラー | 一時的な問題と判断しリトライ |
リトライロジックの実装例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
async function safeApiCall() { let retryCount = 3; while (retryCount > 0) { try { const res = await client.api(...); return res; } catch (e) { if (e.statusCode === 500 && retryCount > 1) { retryCount--; continue; } throw e; } } } |
サービス構築の全体像と実装フロー
本ガイドで説明した内容をまとめると以下のような流れになります。
- アカウント登録（Client ID/Secret取得）
- SDK導入（@atproto/apiインストール）
- 認証フロー実装（OAuth 2.0によるトークン取得）
- 投稿API利用（投稿内容の作成と送信）
- タイムライン取得（投稿データの読み込み）
- エラーハンドリング（異常時のロジック構築）
すべてのステップを実施することで、Bluesky APIを用いた基本的なWebサービス構築が可能になります。
実装にあたっては公式ドキュメント（https://docs.bsky.app/）との併用を強くお勧めします。