Hatena::Grouphatenadeveloper

Hatena Haiku APIs - Data formats

en/haiku/apis/rest/datatypes

Hatena Haiku APIs — Data formats

Notice on this document

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

Formats for the data returned by APIs

Hatena Haiku RESTful APIs, if the specified operation has been succeeded, return the result data in JSON/JSONP or XML, depending on the extension part of the request URL (.json or .xml, respectively).

If the extension is .json, the result data is encoded in JSONP when the query component of the request URL includes the parameter callback, or in JSON otherwise. The callback parameter value is used as the JavaScript method name in JSONP response.

If the extension is .xml, the result data is encoded in plain XML — an XML 1.0 document with no DTD, no namespaces.

In any case, the result data is encoded in UTF-8. Note that the data returned by APIs might or might not include characters that are illegal according to relevant specifications; for example, although XML 1.0 prohibits use of most C0 control characters, if such characters are included in Hatena Haiku entries, APIs output such characters as is.

APIs return appropriate status code including 400, 401, or 404, upon the failure of the operation. In these cases, the extension in the URL might not affect the format of the response body.

Format of data accepted by APIs

When you would like to specify parameters to the API, encode them in the application/x-www-form-urlencoded format and include in the query component of request URL if the HTTP request method is GET, or in the entity-body if the HTTP request method is POST. Strings MUST be encoded in UTF-8.

If the HTTP request method is POST, you can encode the parameters in the multipart/form-data format instead.

Entries

The Entry object (status element) contains the following values:

NameDescriptionDatatype#
linkEntry page URLURL1
created_atPosted date and timeDatetime1
favoritedNumber of starred usersNumber1
haiku_textNew in Hatena Haiku 1.1 Body (text with Hatena Notations)String0-1
htmlNew in Hatena Haiku 1.1 Body (HTML)String0-1
html_touchNew in Hatena Haiku 1.1 Body (HTML for smartphones)String0-1
html_mobileNew in Hatena Haiku 1.1 Body (HTML for Japanese mobile phones)String0-1
idEntry IDNumber1
in_reply_to_status_idIn-reply-to entry ID (empty string if the entry is not a reply)Number0-1
in_reply_to_user_idIn-reply-to entry's author's Hatena ID (empty string if the entry is not a reply)String0-1
keywordword of the keyword the entry has been posted toString0-1
replies (JSON)Replies for this entryArray of Entry objects0-1
replies (XML)Reply for this entryContent of an Entry object0-∞
sourcePosting agent (from; empty string if unknown)String1
targetNew in Hatena Haiku 1.1 The keyword the entry has been posted toTarget0-1
textBody (Hatena Haiku 1.0 API format)String0-1
userAuthorUser1

New in Hatena Haiku 1.1 Which of haiku_text, html, html_touch, html_mobile, and text are included in the Entry object can be specified by the parameter body_formats.

In JSON format, replies's value is an array of Entry objects representing reply entries for the entry. In XML format, the status element representing the Entry contains zero or more replies elements, each of the elements represents the Entry objects for the reply entries except that the replies element is used instead of the status element.

The Entry objects representing reply entries for another Entry object does not contain in_reply_to_status_id, in_reply_to_user_id, keyword, replies, and target.

The body_formats parameter

The parameter body_formats can be specified for APIs returning an Entry object or a list of Entry objects. This parameter contain one or more values from the following table, separated by , (a comma character):

apiInclude text in the Entry objects
haikuInclude haiku_text in the Entry objects
htmlInclude html in the Entry objects
html_mobileInclude html_mobile in the Entry objects
html_touchInclude html_touch in the Entry objects

Entry bodies

The haiku_text field of the Entry object contain original body text as posted by the user. This text might or might not contain Hatena Notation for Hatena Haiku. For more information on Hatena Notation for Hatena Haiku, please consult Hatena Haiku Help. Note that Hatena Notation for Hatena Haiku differs from Hatena Notation for Hatena Diary.

The text field of the Entry object contain the string Hatena Haiku 1.0 APIs had been set to the text field. It converts some of Hatena Notations into text format, but the others of Hatena Notations are left unchanged.

The html, html_touch, and html_mobile fields of the Entry object contain the body text with its Hatena Notations completely replaced by appropriate HTML tags, as used in PC, smartphone, and Japanese mobile phone versions of Hatena Haiku Web site respectively.

Users

The User object (user element) contains the following values:

NameDescriptionDatatype#
followers_countNumber of fansNumber1
nameNickname (if specified by the user; otherwise Hatena ID)String1
idHatena IDString1
profile_image_urlProfile icon image URLURL1
screen_nameHatena IDString1
urlEntries page's URLURL1

Keywords

The Keyword object (keyword element) contains the following values:

NameDescriptionDatatype#
entry_countNumber of entriesNumber1
followers_countNumber of fansNumber1
linkEntries page's URLURL1
related_keywords (JSON)Array of words of some related keywordsArray0-1
related_keywords (XML)word of a related keywordString0-∞
titleTitle of the keyword pageString1
wordKeyword string that can be used in "keyword" form fieldString1
url_nameNew in Hatena Haiku 1.1 Name as used in URLsString0-1

The word field contains the string the can be specified to the Keyword field in the entry form. The title field contains the string contained in headings in the keyword page. They are sometimes different - for example, the word for a product keyword contains asin: followed by alphabetical symbols, while the title contains the product name in human readable form.

New in Hatena Haiku 1.1 Whether related_keywords are included in the Keyword objects or not can be specifed by the parameter without_related_keywords.

If related_keywords are included, in the JSON format, a JSON array of the words of some related keywords are included in related_keywords. This array might be empty. In the XML format, the word of each related keyword is included as a related_keywords element.

The url_name field is not included if it is not assigned yet.

Targets

New in Hatena Haiku 1.1

The Target keyword object (target element) contains the following values:

NameDescriptionDatatypes#
titleTitle of the keyword pageString1
wordKeyword string that can be used in "keyword" form fieldString1
url_nameName as used in URLsString0-1

The url_name field is not included if it is not assigned yet.

Arrays

In the JSON format, arrays are represented as JSON array.

In the XML format, arrays are represented as elements whose name is determined by the element names of items. In any case, the element has the type attribute set to array.

Element name of the array itemsElement name of the array itself
keywordkeywords
statusstatuses
userusers

Other datatypes

If a value is boolean, False is represented by null, number 0, or string 0; True is represented by any other value.

If a value is number, it is represented by the number itself or by its string representation.

If a value is datetime, it is represented by a valid global date and time string.

In Hatena Haiku APIs, HTTP datetime refers to rfc1123-date in RFC 2616.

A URL is represented as an absolute URL.

URL construction

Document URL construction describes how to construct URLs of Hatena Haiku Web site from objects returned by Hatena Haiku APIs.

History

  • February 14, 2011 Published.