Hatena::Grouphatenadeveloper

はてなメッセージ受信箱・送信箱 API

ja/message/apis/box

はてなメッセージ受信箱・送信箱 API

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

本ドキュメントははてなメッセージの受信箱・送信箱の取得を行う API について解説するものです。

はてなメッセージ受信箱・送信箱 API の概要

はてなメッセージ受信箱・送信箱 API は、 OAuth 認証を利用した REST API です。 HTTP の GET を特定の URL に対して行うことで、あるはてなユーザーのはてなメッセージの受信箱・送信箱の内容を取得できます。

現在、本APIは一部の限られたメッセージにのみアクセスできます。はてなメッセージ Web サイト上の一覧とは異なりますので、ご注意ください。

認証

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

はてなメッセージの取得には read_private 操作の承認を得ている必要があります。

受信箱 (/inbox.json)、送信箱 (/outbox.json)

はてなメッセージの受信箱、送信箱はそれぞれ

http://m2.hatena.com/inbox.json
http://m2.hatena.com/outbox.json

... に対して HTTP GET メソッドによりアクセスすることで取得できます。現在、本APIは一部の限られたメッセージにのみアクセスできます。はてなメッセージ Web サイト上の一覧とは異なりますので、ご注意ください。

HTTP 要求に含める引数

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

引数名引数値個数
location 取得するサービス 0-1 (省略時はすべて)
per_page 取得する最大の個数 0-1 (省略時は自動決定)
reftime 取得範囲の指定 0-1 (省略時は自動決定)

location には、次のいずれかの値を指定できます。

http://c.hatena.ne.jp/はてなココ関連のメッセージのみ
http://ugomemo.hatena.ne.jp/うごメモはてな関連のメッセージのみ

HTTP 応答

取得または変更に失敗しなかった場合、 200 (OK) などの成功を表す応答が返されます。 HTTP 応答の本体は次のような JSON オブジェクトとなります。

items メッセージの配列
newer_url より新しいメッセージを取得するための URL
older_url より古いメッセージを取得するための URL

メッセージは次のような JSON オブジェクトです。該当する値が無いときは省略されるか、値が null となります。

owner_entity メッセージ所有者を表す対象オブジェクト
from_entity メッセージ送信者を表す対象オブジェクト
to_entity メッセージ受信者を表す対象オブジェクト
date メッセージの日付
mid メッセージID
mid_as_url メッセージID (URL 形式)
title_prefix タイトルのうちサービス名を表す部分
title タイトル本体
type メッセージ種別
body_as_plain_text 本文 (テキスト)
body_as_html 本文 (HTML)
body_movie_info うごメモはてなでの各種 URL を表すオブジェクト
url はてなメッセージでの当該メッセージ URL

2013年5月31日のうごメモはてなサービス終了以後は、うごレターの本文など一部の情報を取得できなくなります。ご注意ください。

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

GET /inbox.json HTTP/1.1
Host: m2.hatena.com
Authorization: OAuth ...
User-Agent: ExampleUserAgent/1.0

HTTP/1.1 200 OK
Content-Type: application/json

{
  "older_url": "http://m2.hatena.com/...",
  "newer_url": "http://m2.hatena.com/...",
  "items": [
    {
      "mid": "12345678901234567890",
      "url": "http://m2.hatena.ne.jp/m/12345678901234567890",
      "owner_entity": {
        "display_name": "Sample",
        "url_name": "sample"
      },
      "from_entity": {
        "display_name": "Sample",
        "url_name": "sample"
      },
      "to_entity": {
        "display_name": "You"
      },
      "title": "Hello, world!",
      "body_as_plain_text": "Hello, world!  Happie Hatena life!",
      ...
    }
  ]
}

変更履歴

  • 2013年4月11日 API 仕様を公開