Hatena::Grouphatenadeveloper

Hatena Message Inbox/Outbox API

en/message/apis/box

Hatena Message Inbox/Outbox API

Overview

The Hatena Message Inbox/Outbox API is an OAuth-based RESTful API. With this API, you can retrieve inbox and outbox of Hatena Message through HTTP GET requests.

At the moment the API only returns limited kinds of messages. Please note that, in particular, it returns different set of messages from those listed in the Hatena Message Web site.

Authentication

The API supports OAuth-based user authentication. You can obtain Consumer Keys for the OAuth access from the Access Hatena services with OAuth section in your User Settings. There is a tutorial document はてなサービスにおける OAuth (available only in Japanese at the time of writing, but sample codes are also included there).

The scope read_private is required for all operations in the API.

inbox (/inbox.json) and Outbox (/outbox.json)

The inbox and outbox of Hatena Message can be retrieved by accessing following URLs by HTTP GET method, respectively:

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

At the moment the API only returns limited kinds of messages. Please note that, in particular, it returns different set of messages from those listed in the Hatena Message Web site.

Parameters in HTTP requests

The following parameter can be included in HTTP requests in the application/x-www-form-urlencoded format:

Parameter nameParameter value#
location Services 0-1 (All services if omitted)
per_page Maximum # of messages 0-1 (Auto if omitted)
reftime Range of retrieved messages 0-1 (Auto if omitted)

location can be one of following values:

http://c.hatena.ne.jp/Hatena Coco
http://ugomemo.hatena.ne.jp/Flipnote Hatena

HTTP responses

If the retrieval or updating has not failed, a success response such as 200 (OK) is returned. The HTTP response body is a JSON object containing following properties:

items Array of messages
newer_url URL for retrieving newer messages
older_url URL for retrieving older messages

A message is a JSON object with following properties:

owner_entity Target object of the owner of the message
from_entity Target object of the sender of the message
to_entity Target object of the receiver of the message
date Timestamp of the message
mid Message ID
mid_as_url Message ID (as a URL)
title_prefix Service name in the title
title Title (core part)
type Message type
body_as_plain_text Body (plain text)
body_as_html Body (HTML)
body_movie_info An object containing URLs in Flipnote Hatena
url URL of the message in Hatena Message Web site

If there is no applicable value for the property, the property might be ignored or take the null value.

Please note that certain properties of Ugoletters will not be available after shutdown of Flipnote Hatena at May 31, 2013.

If the retrieval or updating has failed, an error response such as 400 (Bad Request) or 401 (Authorization Required) is returned.

Example

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!",
      ...
    }
  ]
}

Changes

  • April 11, 2013 Published