Hatena::Grouphatenadeveloper

はてなのともだち関係設定 API

ja/nano/friends/modify

はてなのともだち関係設定 API

本ドキュメントに関する注意事項

本ドキュメントははてなの「ともだち」の関係を設定する API について解説するものです。

はてなのともだち関係設定 API の概要

はてなのともだち関係設定 API は、 OAuth 認証を利用した REST API です。 HTTP の POST を特定の URL に対して行うことで、あるはてなユーザーから別のユーザーにともだち申請したり、ともだち申請を受理したり、ともだち関係を解消したりすることができます。

現在次の2つの API を提供しています。

認証

本 API は OAuth によるユーザー認証に対応しています。 OAuth 認証の詳細に関しては、はてなのOAuthを利用する方法を参照してください。

ともだち関係の設定には write_private 操作の承認を得ている必要があります。

ともだち状態の変更 (/USERNAME/relation)

ともだち状態の変更は、

http://n.hatena.com/USERNAME/relation

... に対して HTTP POST メソッドによりアクセスすることで行います。認証しているユーザーから見た USERNAME とのともだち関係が変更されます。将来的に http から https に移行する可能性がございますので、ご注意ください。

HTTP 要求に含める引数

HTTP 要求には application/x-www-form-urlencoded 形式で次の引数を含めることができます。

引数名引数値個数
flidともだちになったときに相手を追加するともだちグループのID1個まで (省略すると指定なし)
locationサービスを表す URL1個 (必須)
messageともだち申請メッセージに入れるコメント1個まで (省略すると指定なし)
operation承認操作なら add、拒否操作なら deny1個 (必須)

お互いにともだちでない状態で operation=add を実行すると、ともだち申請状態となり、ともだち申請メッセージが送信されます。既に相手からともだち申請されている状態で operation=add を実行すると、その場でともだちになります。 operation=deny を実行すると、ともだち状態やともだち申請状態が解除されます。以上の状況以外では何も変更を行いません。

locationhttp://c.hatena.ne.jp/ を設定すると、はてなココのともだち申請メッセージが送られます。同様に http://h.hatena.ne.jp/ ではてなハイクのともだち申請メッセージとなります。

HTTP 応答

変更に失敗しなかった場合、 200 (OK) などの成功を表す応答が返されます。その応答の X-Nano-Friend-Status: ヘッダーフィールドに新しいともだち関係が入ります。ともだち関係は friend (ともだち)、 requesting (こちらからともだち申請中)、 requested (あちらからともだち申請されている)、 none (それ以外) のいずれかで表されます。

変更に失敗した場合、 400 (Bad Request)、 401 (Authorization Required) などの HTTP 応答が返されます。

POST /sample/relation HTTP/1.1
Host: n.hatena.com
Authorization: OAuth ...
User-Agent: ExampleUserAgent/1.0

operation=add&message=Hello!&location=http://c.hatena.ne.jp/
HTTP/1.1 200 OK
X-Nano-Friend-Status: friend

...

ともだち関係の説明の変更 (/USERNAME/relation/label/edit)

ともだち関係の説明の変更は、

http://n.hatena.com/USERNAME/relation/label/edit

... に対して HTTP POST メソッドによりアクセスすることで行います。認証しているユーザーから見た USERNAME とのともだち関係が変更されます。将来的に http から https に移行する可能性がございますので、ご注意ください。

HTTP 要求に含める引数

HTTP 要求には application/x-www-form-urlencoded 形式で次の引数を含めることができます。

引数名引数値個数
labelともだち関係の説明文 (削除したいときは空文字列)1個 (必須)

HTTP 応答

変更に失敗しなかった場合、 204 (No Content) などの成功を表す応答が返されます。変更に失敗した場合、 400 (Bad Request)、 401 (Authorization Required) などの HTTP 応答が返されます。

POST /sample/relation/label/edit
Host: n.hatena.com
Authorization: OAuth ...
User-Agent: ExampleUserAgent/1.0

label=My%20Important%20Friend
HTTP/1.1 204 No Content

関連ドキュメント

はてなのともだち情報取得 API
ともだちやともだち申請中の人の一覧を取得することができます。

変更履歴

  • 2010年12月13日 API 仕様を公開
  • 2012年10月1日 はてなハイク2の記述を削除