Contents
はてなブックマークREST APIの認証フローと連携手順を解説
現在、はてなブックマークAPIはOAuth2.0による認証が必須となっており、ウェブサービスとの連携においてセキュリティと柔軟性を両立させる重要な技術です。本記事では、REST APIエンドポイントの利用方法から認証フローまで、実務で即活用できる手順を解説します。
REST APIエンドポイント一覧
はてなブックマークAPIには、ユーザー認証が必要なREST系エンドポイントと、認証不要のjsonliteエンドポイントの2種類があります。REST系エンドポイントはデータ操作が可能ですが、jsonliteは情報取得のみです。
主なエンドポイント一覧
| エンドポイント | 用途 | リクエスト方法 |
|---|---|---|
| GET /api/1.0/users/{username}/bookmarks | 指定ユーザーのブックマークリスト取得 | OAuth認証必須 |
| POST /api/1.0/bookmarks | 新規ブックマーク投稿 | OAuth認証必須 |
| DELETE /api/1.0/bookmarks/{id} | 特定IDのブックマーク削除 | OAuth認証必須 |
| GET /jsonlite/1.0/users/{username}/bookmarks | 認証不要でブックマークリスト取得（限定情報） | 認証不要 |
本APIはJSON形式での応答を標準とし、リクエストごとにUser-Agentの指定が求められます。
OAuth2.0認証フローの詳細
OAuth2.0を用いた認証フローでは、3つのステップでアクセストークンを取得します。以下に手順を具体的に解説します。
認証フローのステップ1: アクセスコード取得
アプリケーション側から認証サーバーにリダイレクトURIを指定してアクセスコードを依頼します。この際、クライアントIDとリダイレクトURIが必要です。
具体的には、以下のようなURLで認証フローを開始します：
|
1 2 |
https://www.hatena.ne.jp/login/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback |
ステップ2: アクセストークン発行
取得したアクセスコードとクライアントシークレットを使って、アクセストークンの交換リクエストを送信します。このトークンは1時間程度有効なため、定期的な刷新が必要です。
ステップ3: API呼び出し時のアクセストークン利用
アクセストークンをAuthorization: Bearer <token>というヘッダー形式でAPIに添付することで、ユーザーの操作権限を取得できます。トークンが無効または期限切れの場合、エラーレスポンスとして401が返されます。
JSON形式レスポンスの解析方法
はてなブックマークAPIの応答はすべてJSON形式で返却され、以下のような構造をとります。
レスポンス例（成功時）
|
1 2 3 4 5 6 7 8 9 10 11 12 |
{ "bookmarks": [ { "id": "1234567890", "url": "https://example.com", "title": "サンプル記事", "tags": ["tech", "web"] } ], "has_next": true } |
エラーレスポンス例（認証失敗時）
|
1 2 3 4 5 6 7 |
{ "error": { "code": 401, "message": "アクセストークンが無効です" } } |
JSON解析には言語に応じた関数を使用します。以下は代表的な例です：
- PHP：
json_decode() - Python：
json.loads() - JavaScript：
JSON.parse() - Java：
ObjectMapper.readTree()（Jacksonライブラリ使用時） - C#：
JsonConvert.DeserializeObject()（Newtonsoft.Json使用時）
レート制限対策のベストプラクティス
はてなブックマークAPIにはリクエスト制限が設定されており、過剰なアクセスを行った場合に自動的に制限されることがあります。以下に回避策を紹介します。
クライアント側での対応ポイント
- リトライメカニズムの実装: 429エラー（Too Many Requests）が返された場合、指数バックオフ方式で再試行を行う
- キャッシュ戦略: 同じパラメータで複数回アクセスするケースでは結果をキャッシュし、API呼び出し回数を減らす
- スレッド制御: マルチスレッド環境での並行リクエストを制限し、負荷分散を行う
はてな側の仕様では、User-Agentの正しく指定しないアクセスは予告なしに制限される可能性があります。
サンプルコード提供（PHP/Python）
公式ドキュメントに記載されたフローを基に、簡潔なサンプルコードを公開します。コード内には各ステップの説明コメントを付与しています。
PHPでのOAuth認証とAPI呼び出し例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
// 1. 認証コード取得（リダイレクトURI経由） $auth_url = "https://www.hatena.ne.jp/login/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback"; // 2. アクセストークン発行 $post_data = [ 'grant_type' => 'authorization_code', 'code' => $_GET['code'], 'client_id' => 'YOUR_CLIENT_ID', 'client_secret' => 'YOUR_CLIENT_SECRET', 'redirect_uri' => 'https://yourapp.com/callback' ]; $token_response = json_decode(file_get_contents('https://www.hatena.ne.jp/login/oauth/token', false, stream_context_create([ 'http' => [ 'method' => 'POST', 'header' => "Content-Type: application/json\r\n", 'content' => json_encode($post_data) ] ]))); // 3. API呼び出し（ブックマーク取得） $access_token = $token_response->access_token; $headers = [ "Authorization: Bearer $access_token", "User-Agent: YourApp/1.0" ]; $response = file_get_contents("https://api.hatena.ne.jp/api/1.0/users/hoge/bookmarks", false, stream_context_create([ 'http' => ['header' => implode("\r\n", $headers)] ])); echo json_decode($response); |
Pythonでの同様な実装例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
import requests # 1. 認証コード取得（リダイレクトURI経由） auth_url = "https://www.hatena.ne.jp/login/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback" # 2. アクセストークン発行 post_data = { 'grant_type': 'authorization_code', 'code': input("認証コードを入力してください: "), 'client_id': 'YOUR_CLIENT_ID', 'client_secret': 'YOUR_CLIENT_SECRET', 'redirect_uri': 'https://yourapp.com/callback' } token_response = requests.post('https://www.hatena.ne.jp/login/oauth/token', json=post_data).json() # 3. API呼び出し（ブックマーク取得） access_token = token_response['access_token'] headers = { 'Authorization': f'Bearer {access_token}', 'User-Agent': 'YourApp/1.0' } response = requests.get('https://api.hatena.ne.jp/api/1.0/users/hoge/bookmarks', headers=headers).json() print(response) |
サンプルコードは公式ドキュメントと併せて実装してください。環境に応じてクライアントライブラリ（例:
requests-oauthlib）を活用することも可能です。
まとめ
- REST APIエンドポイントの利用にはOAuth2.0認証が必要
- 認証フローは3ステップ構成で、アクセストークンの取得と有効期限管理が重要
- JSONレスポンスの解析に加え、401/429エラー処理を実装する
- レート制限対策として、リトライメカニズムやキャッシュ戦略を組み込む
- PHP・Pythonいずれの言語でも、公式ドキュメントと併せて簡単なサンプルコードで連携可能
本記事を参考に、はてなブックマークAPIとの連携を実装してみてください。