Hatena::Grouphatenadeveloper

はてなハイク API のデータの書式

ja/haiku/apis/rest/datatypes

はてなハイク API のデータの書式

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

本ドキュメントははてなハイク REST API の解説の一部です。

API が返すデータの書式

はてなハイク REST API は、処理が成功した場合に JSON/JSONP または XML により結果を返します。どちらが返されるかは URL の拡張子が .json か .xml のいずれであるかによって決まります。

拡張子が .json の場合は、 URL の query 部分または POST の entity-body に callback 引数が指定されている場合は JSONP、指定されていない場合は JSON となります。 JSONP の場合に呼び出される JavaScript メソッドの名前は callback 引数の値となります。

XML 形式は、 XML 名前空間や DTD を使っていない単純な XML 1.0 文書となっています。

どちらの場合も、 UTF-8 により符号化されています。 API が返すデータには仕様上不正な文字列が含まれる可能性があります。例えば、 XML 1.0 仕様はほとんどの C0 制御文字の使用を認めていませんが、はてなハイクの投稿に含まれていれば API はそのまま出力します。

はてなハイク REST API は、処理が失敗した場合には 400, 401, 404 などの HTTP 応答を返します。この場合、 URL の拡張子に指定された書式で結果が返されるとは限りません。

API に渡すデータの書式

はてなハイク REST API に引数を指定する場合、 HTTP の GET メソッドであれば URL の query 部分に、 POST メソッドであれば entity-body に application/x-www-form-urlencoded 形式で記述してください。文字列はすべて UTF-8 により符号化しておく必要があります。

HTTP の POST メソッドを使用する場合は、 application/x-www-form-urlencoded 形式のかわりに multipart/form-data 形式としても構いません。

投稿

投稿オブジェクト (status 要素) には、次の値が含まれます。

名前値の意味値のデータ型個数
link投稿単体のページの URLURL1
created_at投稿日時日時1
favoritedスターを付けたユーザーの数数値1
haiku_textはてなハイク1.1の新機能 投稿本文 (はてな記法入りテキスト)文字列0-1
htmlはてなハイク1.1の新機能 投稿本文 (HTML)文字列0-1
html_touchはてなハイク1.1の新機能 投稿本文 (スマートフォン用 HTML)文字列0-1
html_mobileはてなハイク1.1の新機能 投稿本文 (携帯電話用 HTML)文字列0-1
id投稿 ID数値1
in_reply_to_status_id返信先の投稿 ID (返信でなければ空文字列)数値0-1
in_reply_to_user_id返信先の投稿者のはてな ID (返信でなければ空文字列)文字列0-1
keyword投稿先キーワードの word文字列0-1
replies (JSON)返信投稿の配列0-1
replies (XML)返信投稿の内容0-∞
source投稿元 (from、不明なら空文字列)文字列1
targetはてなハイク1.1の新機能 投稿先キーワード対象0-1
text投稿本文 (はてなハイク1.0 API 形式)文字列0-1
user投稿者ユーザー1

はてなハイク1.1の新機能 haiku_text, html, html_touch, html_mobile, text のどれを投稿オブジェクトに含めるかは、 API への body_formats 引数によって指定できます。

replies は、 JSON 形式では返信を表す投稿オブジェクトの配列が値となります。 XML 形式では、返信を表す status 要素の要素名を replies に変えたものが親投稿の status 要素の子要素となります。

返信を表す投稿オブジェクトには、 in_reply_to_status_id, in_reply_to_user_id, keyword, replies, target は含まれません。

body_formats 引数

投稿や投稿のリストを返す API には、 body_formats 引数を指定することができます。この引数には、次の値を , で区切って1つ以上含めることができます。

apitext を投稿オブジェクトに含めます。
haikuhaiku_text を投稿オブジェクトに含めます。
htmlhtml を投稿オブジェクトに含めます。
html_mobilehtml_mobile を投稿オブジェクトに含めます。
html_touchhtml_touch を投稿オブジェクトに含めます。

投稿本文

投稿オブジェクトの haiku_text には、ユーザーが入力した元の投稿文が含まれます。この投稿文には、通常の文字列の他に、はてなハイク用のはてな記法が含まれていることがあります。はてなハイク用のはてな記法についてははてなハイクのヘルプをご参照ください。なお、はてなハイクのはてな記法ははてなダイアリーのはてな記法とは異なっています。

投稿オブジェクトの text には、はてなハイク1.0 API が text に含めていた文字列が含まれます。この文字列は、ユーザーが入力した投稿文の一部のはてな記法を解釈し、テキスト化したものです。

投稿オブジェクトの html, html_touch, html_mobile は投稿文のはてな記法を解釈し HTML 化したものです。それぞれ、はてなハイクのパソコン版、スマートフォン版、モバイル版で使われているものに相当します。

ユーザー

ユーザーオブジェクト (user 要素) には、次の値が含まれます。

名前値の意味値のデータ型個数
followers_countファンの数数値1
nameニックネーム (設定されていない場合ははてな ID)文字列1
idはてな ID文字列1
profile_image_urlプロフィール画像の URLURL1
screen_nameはてな ID文字列1
urlユーザーのエントリーページの URLURL1

キーワード

キーワードオブジェクト (keyword 要素) には、次の値が含まれます。

名前値の意味値のデータ型個数
entry_count投稿数数値1
followers_countファンの数数値1
linkキーワードのエントリーページの URLURL1
related_keywords (JSON)主要な関連キーワードの名前の配列配列0-1
related_keywords (XML)主要な関連キーワードの名前文字列0-∞
titleキーワードの表示上のタイトル文字列1
wordキーワードとして指定する文字列文字列1
url_nameはてなハイク1.1の新機能 URL で使用する名前文字列0-1

word はトップページの投稿フォームのキーワード欄に指定できる文字列です。 title はキーワードページの見出しとして表示される文字列です。キーワードによっては両者が異なることがあります。例えば商品ページでは wordasin: からはじまる記号列になりますが、 title は商品名となります。

はてなハイク1.1の新機能 related_keywords を結果に含めるかどうかは API への without_related_keywords 引数により指定できます。

related_keywords を結果に含める場合、 JSON 形式では関連キーワードの word の配列が related_keywords となります。この配列は空のこともあります。 XML 形式では、関連キーワードそれぞれの wordrelated_keywords 要素として含められます。

url_name は、存在しない場合には含まれません。

対象

はてなハイク1.1の新機能

投稿の対象となるキーワードのオブジェクト (target 要素) には、次の値が含まれます。

名前値の意味値のデータ型個数
titleキーワードの表示上のタイトル文字列1
wordキーワードとして指定する文字列文字列1
url_nameはてなハイク1.1の新機能 URL で使用する名前文字列0-1

url_name は、存在しない場合には含まれません。

配列

JSON 形式では、配列はそのまま JSON の配列として表します。

XML 形式では、配列は含まれる要素によって違う名前の要素で表します。いずれの場合も、 type 属性の値は array とします。

配列の要素の要素名配列自体の要素名
keywordkeywords
statusstatuses
userusers

その他

boolean は、偽を null、数値の 0、文字列の 0 のいずれかにより、真をそれ以外の値により表します。

数値は、数値または数値を文字列化したものによって表します。

日時は、妥当な大域日時文字列によって表します。

はてなハイクAPIでは、「HTTP の日時」とは RFC 2616 における rfc1123-date を意味します。

URL は、絶対 URL によって表します。

URL の組み立て

ドキュメント「URL の組み立て」では、はてなハイク API が返したオブジェクトからはてなハイク Web サイトの URL を組み立てる方法を説明しています。

変更履歴

  • 2011年2月14日 公開。