Hatena::Grouphatenadeveloper

Hatena Haiku Entry and Star APIs

en/haiku/apis/rest/entries

Hatena Haiku Entry and Star APIs

Notice on this document

This document is part of the Hatena Haiku RESTful APIs documentation.

Overview of Entry and Star APIs

Hatena Haiku Entry and Star APIs can be used to post, retrieve, and delete entries and stars.

NameOperations
statuses/updatePost a new entry
statuses/showRetrieve an entry
statuses/destroyDelete an entry
favorites/createAdd a star to the entry
favorites/destroyDelete a star from the entry

statuses/update

Post a new entry to Hatena Haiku. The author of the newly posted entry is the authenticated user.

URL

http://{domain}/api/statuses/update.{format}?{parameters}
{domain}Hatena Haiku domain name; h.hatena.ne.jp for Japanese version, h.hatena.com for global version.
{format}Format of the result; json or xml.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

OAuth (write_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP POST method.

Parameters

Following parameters are available: callback, file, keyword, in_reply_to_status_id, status, source, New in Hatena Haiku 1.1 body_formats

Specify the keyword to which the entry is posted in the parameter keyword. The keyword has to be specified in the format the Target keyword object's word field would contain. If the keyword does not exist, it is automatically created when the first entry is posted.

Specify the body text to post in the parameter status. It may contain Hatena Notations as in the Hatena Haiku Web site.

If the keyword parameter is missing, and if the status parameter contains a = character, the substring before the character is considered as the keyword and they are excluded from the posted body text. As this is very confusing, you are advised to always contain the parameter keyword in the request.

If the keyword is not specified at all, the entry is posted to the user keyword, i.e. the keyword whose word is id: followed by the user's Hatena ID.

If image files are specified in the parameter file, the images are uploaded to Hatena Fotolife and the images are included at the end of the body text. If the parameter file is specified, the entity-body MUST be encoded in multipart/form-data. New in Hatena Haiku 1.1 The parameter file can be specified at most four (4) times.

At most one of status and file parameters MUST be specified.

If the parameter in_reply_to_status_id contains the ID of another entry, the new entry becomes a reply to the specified entry.

Obsolete If @{id} is specified at the beginning of the parameter status, the entry becomes a reply to the last entry by {id}. This is not applied when the parameter in_reply_to_status_id is specified. This feature is not available in Hatena Haiku 1.1 or later.

The parameter source specifies the posting client name by which the entry is posted. It is shown in the from field of the entry in Hatena Haiku Web site. It becomes the link to the keyword for the client. If there is no such keyword, a new keyword is created. The client name is also used as the client name for uploading the images to the Hatena Fotolife, when the parameter file is specified. The default value is API.

Result

If succeeded, the Entry object representing the newly posted entry is returned.

statuses/show

Return the entry specified by ID. It corresponding to the entry page in the Web site, i.e. http://h.hatena.com/{username}/{eid}.

URL

http://{domain}/api/statuses/show/{eid}.{format}?{parameters}
{domain}Hatena Haiku domain name; h.hatena.ne.jp or h.hatena.com, as you like.
{format}Format of the result; json or xml.
{eid}The ID of the entry.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

Authentication is unnecessary.

Method

Use the HTTP GET method.

Parameters

Following parameters are available: callback, New in Hatena Haiku 1.1 body_formats

Result

If succeeded, the Entry object is returned.

statuses/destroy

Delete the specified entry from Hatena Haiku. An entry can be deleted by the author of the entry or, if the entry is posted to a user keyword, the user.

URL

http://{domain}/api/statuses/destroy/{eid}.{format}?{parameters}
{domain}Hatena Haiku domain name; h.hatena.ne.jp or h.hatena.com, as you like.
{format}Format of the result; json or xml.
{eid}The ID of the entry.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

OAuth (write_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP POST method.

Parameters

Following parameters are available: callback, New in Hatena Haiku 1.1 author_url_name, body_formats

Specify the Hatena ID of the author of the entry in the parameter author_url_name. Though this parameter is optional, it is encouraged to specify it anyway.

Result

If succeeded, the Entry object for the deleted entry is returned.

favorites/create

Add a star (yellow Hatena Star) to the specified entry by the authenticated user.

URL

http://{domain}/api/favorites/create/{eid}.{format}?{parameters}
{domain}Hatena Haiku domain name; h.hatena.ne.jp or h.hatena.com, as you like.
{format}Format of the result; json or xml.
{eid}The ID of the entry.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

OAuth (write_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP POST method.

Parameters

Following parameters are available: callback, New in Hatena Haiku 1.1 body_formats

Result

If succeeded, the Entry object for the entry is returned.

favorites/destroy

Delete a star by the authenticated user, if any, from the entry.

URL

http://{domain}/api/favorites/destroy/{eid}.{format}?{parameters}
{domain}Hatena Haiku domain name; h.hatena.ne.jp or h.hatena.com, as you like.
{format}Format of the result; json or xml.
{eid}The ID of the entry.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

OAuth (write_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP POST method.

Parameters

Following parameters are available: callback, New in Hatena Haiku 1.1 body_formats

Result

If succeeded, the Entry object for the entry is returned.

Examples

GET http://h.hatena.com/api/statuses/show/12345678901234.xml

<status>
    <id>12345678901234</id>
    <created_at>2008-08-19T00:00:00Z</created_at>
    <favorited>0</favorited>
    <in_reply_to_status_id/>
    <in_reply_to_user_id/>
    <keyword>key</keyword>
    <link>http://h.hatena.com/jkondo/12345678901234</link>
    <source>web</source>
    <text>key=text</text>
    <user>
      <name>jkondo</name>
      <followers_count>1</followers_count>
      <id>jkondo</id>
      <profile_image_url>http://www.hatena.ne.jp/users/jk/jkondo/profile.gif</profile_image_url>
      <screen_name>jkondo</screen_name>
      <url>http://h.hatena.com/jkondo/</url>
    </user>
</status>

GET http://h.hatena.com/api/statuses/show/12345678901234.json

{
    "source" : "web",
    "keyword" : "key",
    "favorited" : 0,
    "created_at" : "2008-08-19T00:00:00Z",
    "text" : "key=text",
    "link" : "http://h.hatena.com/jkondo/12345678901234",
    "in_reply_to_user_id" : 0,
    "user" : {
        "followers_count" : 1,
        "profile_image_url" : "http://www.hatena.ne.jp/users/jk/jkondo/profile.gif",
        "url" : "http://h.hatena.com/jkondo/",
        "name" : "jkondo",
        "id" : "jkondo",
        "screen_name" : "jkondo"
    },
    "id" : "12345678901234",
    "in_reply_to_status_id" : 0
}

POST http://h.hatena.com/api/favorites/create/12345678901234.xml

A star is added to the entry.

<status>
    <id>12345678901234</id>
    <created_at>2008-08-18T00:00:00Z</created_at>
    <favorited>1</favorited>
    <in_reply_to_status_id>98765432109876</in_reply_to_status_id>
    <in_reply_to_user_id>jkondo</in_reply_to_user_id>
    <keyword>KEYWORD</keyword>
    <link>http://h.hatena.com/jkondo/12345678901234</link>
    <source>web</source>
    <text>TEXT</text>
    <user>
        <name>jkondo</name>
        <followers_count>1</followers_count>
        <id>jkondo</id>
        <profile_image_url>
            http://www.hatena.ne.jp/users/jk/jkondo/profile.gif
        </profile_image_url>
        <screen_name>jkondo</screen_name>
        <url>http://h.hatena.com/jkondo/</url>
    </user>
</status>

POST http://h.hatena.com/api/favorites/create/12345678901234.json

A star is added to the entry.

{
    "source" : "web",
    "link" : "http://h.hatena.com/jkondo/12345678901234",
    "keyword" : "KEYWORD",
    "favorited" : 1,
    "created_at" : "2008-08-18T00:00:00Z",
    "text" : "TEXT",
    "in_reply_to_user_id" : "jkondo",
    "user" : {
        "followers_count" : 1,
        "profile_image_url" : "http://www.hatena.ne.jp/users/jk/jkondo/profile.gif",
        "url" : "http://h.hatena.com/jkondo/",
        "name" : "jkondo",
        "id" : "jkondo",
        "screen_name" : "jkondo"
    },
    "id" : "12345678901234",
    "in_reply_to_status_id" : "98765432109876"
}

History

  • December 13, 2010 Republished in Hatena Developer Center.
  • December 24, 2010 Added new features in Hatena Haiku 1.1 Beta.
  • February 14, 2011 Added new features in Hatena Haiku 1.1.