はてなの OAuth アプリケーション用 API

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

本ドキュメントははてなの OAuth を用いたアプリケーションで共通してご利用いただける API について解説するものです。

はてなの OAuth アプリケーション用 API の概要

はてなの OAuth アプリケーション用 API は、 OAuth を利用した REST API です。 HTTP の GET や POST を特定の URL に対して行うことで、 OAuth を利用しているユーザーの情報を取得したり、アプリケーションの利用開始を通知したりすることができます。

ユーザー情報の取得 (/applications/my.json)
アプリケーション利用開始の通知 (/applications/start)

認証

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

ユーザー情報の取得には read_public 操作、利用開始の通知には write_public 操作の承認を得ている必要があります。

ユーザー情報の取得 (`/applications/my.json`)

OAuth で認証しているユーザーの情報の取得は、

http://n.hatena.com/applications/my.json

... に HTTP GET によりアクセスすることで行います。

HTTP 応答

取得に成功した場合、 200 (OK) 応答によって後述の形式の JSON データが返されます。取得に失敗した場合、 400 (Bad Request)、 401 (Authorization Required) などの HTTP 応答が返されます。

JSON データの形式

JSON データは、次の情報を含むオブジェクトとなっています。

名前	値の意味	値の種類
`url_name`	識別子 (URL の一部として使われる記号列)	文字列
`display_name`	ニックネーム	文字列
`profile_image_url`	プロフィールアイコン	URL

値が存在しないために省略されていることがあります。今後上記以外の情報も予告なく追加することがあります。

例

GET /applications/my.json HTTP/1.1
Host: n.hatena.com
Authorization: OAuth ...
User-Agent: ExampleUserAgent/1.0

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "profile_image_url":"http://www.st-hatena.com/users/sa/sample/profile.gif",
  "url_name":"sample",
  "display_name":"Hatena Sample"
}

アプリケーション利用開始の通知 (`/applications/start`)

OAuth アプリケーション利用開始の通知は、

http://n.hatena.com/applications/start

... に対して HTTP POST メソッドによりアクセスすることで行います。

アプリケーションの利用開始を通知すると、はてなのタイムラインに利用開始を知らせるメッセージが投稿されます。このメッセージには、登録した OAuth アプリケーションの名前やロゴなどが含まれます。

今後、通知メッセージの投稿以外の動作も行うよう拡張する可能性がありますので、ご注意ください。なお、ユーザーの意図に沿わない形で本機能を利用された場合には、 OAuth の利用停止などの措置を取ることがあります。

HTTP 応答

通知に成功した場合、 200 (OK) 応答が返されます。通知に失敗した場合、 400 (Bad Request)、 401 (Authorization Required) などの HTTP 応答が返されます。

例

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"result": 1}

変更履歴

2010年12月13日 API 仕様を公開

はてなの OAuth アプリケーション用 API

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