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

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

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

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

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

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

認証

本 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`	ともだちになったときに相手を追加するともだちグループのID	1個まで (省略すると指定なし)
`location`	サービスを表す URL	1個 (必須)
`message`	ともだち申請メッセージに入れるコメント	1個まで (省略すると指定なし)
`operation`	承認操作なら `add`、拒否操作なら `deny`	1個 (必須)

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

location に http://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 要求に含める引数

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

変更履歴

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

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

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