Hatena::Grouphatenadeveloper

Hatena Haiku Favorites APIs

en/haiku/apis/rest/follows

Hatena Haiku Favorites APIs

Notice on this document

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

Overview of Favorites APIs

Hatena Haiku Favorites APIs can be used to retrieve or modify lists of favorite users and keywords.

NameOperations
statuses/friendsRetrieve the list of favorite users of a user
statuses/followersRetrieve the list of fan users of a user.
friendships/createAdd a user to the favorites
friendships/destroyDelete a user from the favorites
statuses/keywordsRetrieve the list of favorite keywords of a user
keywords/createAdd a keyword to the favorites
keywords/destroyDelete a keword from the favorites

The page parameter

For the APIs to retrieve list of users or keywords, the page number can be specified in the parameter page. The maximum value is 100.

statuses/friends

Return the list of favorite users of the authenticated or the specified user.

URL

http://{domain}/api/statuses/friends/{url_name}.{format}?{parameters}
http://{domain}/api/statuses/friends.{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.
{url_name}The Hatena ID of the user.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

If the URL contains {url_name}, authentication is unnecessary.

If the URL does not contain {url_name}, OAuth (read_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP GET method.

Parameters

Following parameters are available: callback, page

Result

If succeeded, the array of User object is returned.

statuses/followers

Return the list of users who added the authenticated user or the specified user to their favorite lists; in other word, the list of fan users of the user.

URL

http://{domain}/api/statuses/followers/{url_name}.{format}?{parameters}
http://{domain}/api/statuses/followers.{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.
{url_name}The Hatena ID of the user.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

If the URL contains {url_name}, authentication is unnecessary.

If the URL does not contain {url_name}, OAuth (read_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP GET method.

Parameters

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

Result

If succeeded, the array of User object is returned.

friendships/create

Add the specified user to the list of favorites for the authenticated user.

URL

http://{domain}/api/friendships/create/{url_name}.{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.
{url_name}The Hatena ID of the user.
{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

Result

If succeeded, the User object for the added user is returned.

friendships/destroy

Delete the specified user from the list of favorites for the authenticated user. If the specified user is not included in the favorites, it does no action.

URL

http://{domain}/api/friendships/destroy/{url_name}.{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.
{url_name}The Hatena ID of the user.
{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

Result

If succeeded, the User object for the deleted user is returned.

statuses/keywords

Returns the list of favorite keywords of the authenticated or the specified user.

URL

http://{domain}/api/statuses/keywords/{url_name}.{format}?{parameters}
http://{domain}/api/statuses/keywords.{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.
{url_name}The Hatena ID of the user.
{parameters}Parameters in the form name1=value1&name2=value2&....

Authentication

If the URL contains {url_name}, authentication is unnecessary.

If the URL does not contain {url_name}, OAuth (read_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP GET method.

Parameters

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

Result

If succeeded, the array of User object is returned.

If you are not intended to retrieve related keywords of the keyword, you are advised to specify a true value to the parameter without_related_keywords.

Result

If succeeded, the array of the Keyword objects is returned.

keywords/create

Add the specified keyword to the list of favorites for the authenticated user.

URL

http://{domain}/api/keywords/create.{format}?{parameters}
http://{domain}/api/keywords/create/{url_name}.{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.
{parameters}Parameters in the form name1=value1&name2=value2&....
{keyword}Deprecated The word of the keyword. It is encouraged to specify the word parameter instead.

Authentication

OAuth (write_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP POST method.

Parameters

Following parmaeters are available: callback, New in Hatena Haiku 1.1 without_related_keywords, word

If you are not intended to retrieve related keywords of the keyword, you are advised to specify a true value to the parameter without_related_keywords.

Result

If succeeded, the Keyword object for the added keyword is returned.

keywords/destroy

Delete the specified keyword from the list of favorites for the authenticated user. If the specified keyword is not included in the favorites, it does no action.

URL

http://{domain}/api/keywords/destroy.{format}?{parameters}
http://{domain}/api/keywords/destroy/{keyword}.{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.
{parameters}Parameters in the form name1=value1&name2=value2&....
{keyword}Deprecated The word of the keyword. It is encouraged to specify the word parameter instead.

Authentication

OAuth (write_public scope) or Basic authentication is REQUIRED.

Method

Use the HTTP POST method.

Parameters

Following parmaeters are available: callback, New in Hatena Haiku 1.1 without_related_keywords, word

If you are not intended to retrieve related keywords of the keyword, you are advised to specify a true value to the parameter without_related_keywords.

Result

If succeeded, the Keyword object for the deleted keyword is returned.

Examples

GET http://h.hatena.com/api/statuses/friends.xml

<users type="array">
    <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>
    ...
</users>

GET http://h.hatena.com/api/statuses/frineds.json

[
    {
        "followers_count" : 1,
        "url" : "http://h.hatena.com/jkondo/",
        "profile_image_url" : "http://www.hatena.ne.jp/users/jk/jkondo/profile.gif",
        "name" : "jkondo",
        "id" : "jkondo",
        "screen_name" : "jkondo"}
    ,
    ...
]

POST http://h.hatena.com/api/friendships/create/jkondo.xml

Added the favorites.

<user>
    <name>jkondo</name>
    <followers_count>100</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>

POST http://h.hatena.com/api/friendships/create/jkondo.json

Added to the favorites.

{
    "name" : "jkondo",
    "followers_count" : "100",
    "id" : "jkondo",
    "profile_image_url" : "http://www.hatena.ne.jp/users/jk/jkondo/profile.gif",
    "screen_name" : "jkondo",
    "url" : "http://h.hatena.com/jkondo/",
}

GET http://h.hatena.com/api/statuses/keywords.xml

<keywords type="array">
    <keyword>
        <entry_count>10</entry_count>
        <followers_count>100</followers_count>
        <link>http://h.hatena.com/Hatena%20Haiku</link>
        <related_keywords>RELATED_KEYWORD</related_keywords>
        <!-- related_keywords ... -->
        <title>Hatena Haiku</title>
    </keyword>
    <!-- keyword ... -->
</users>

GET http://h.hatena.com/api/statuses/keywords.json

[
    {
        "entry_count" : 10,
        "followers_count" : 100
        "link" : "http://h.hatena.com/Hatena%20Haiku",
        "related_keywords" : ["RELATED_KEYWORD", ... ],
        "title" : "Hatena Haiku",
    }
    ...
]

POST http://h.hatena.com/api/keywords/create/KEYWORD.xml

Added to favorites.

<keyword>
    <status>
    <created_at>2008-08-18T00:00:00Z</created_at>
    <entry_count>13</entry_count>
    <link>http://h.hatena.com/keyword/KEYWORD</link>
    <followers_count>2</followers_count>
    <related_keywords>Hatena Haiku</related_keywords>
    <!-- related_keywords ... -->
    <title>KEYWORD</title>
    </status>
</keyword>

POST http://h.hatena.com/api/keywords/create/KEYWORD.json

Added to favorites.

{
    "related_keywords" : [
        "Hatena Haiku",
        ...
    ],
    "created_at" : "2008-08-18T00:00:00Z",
    "followers_count" : "2",
    "title" : "KEYWORD",
    "link" : "http://h.hatena.com/keyword/KEYWORD",
    "entry_count" : "13"
}

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.