Hatena::Grouphatenadeveloper

はてなブックマークAtomAPI

ja/bookmark/apis/atom

はてなブックマークAtomAPI

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

本ドキュメントははてなブックマークにおける AtomAPI 実装を解説するものです。

はてなブックマークの AtomAPI 実装は The Atom Publishing Protocol 草案に基づいたものです。今後本ドキュメント及びはてなブックマークの AtomAPI 実装は RFC 5023 - The Atom Publishing Protocol に従う形へ変更される可能性があります。

AtomAPI とは

AtomAPI はウェブリソースを出版、編集するためのアプリケーション・プロトコル仕様です。はてなブックマークのAtomAPIを利用することで、開発者ははてなブックマークにブックマークを参照、投稿、編集、削除したりを行うオリジナルのアプリケーションを作成することができます。

AtomAPIについて詳しくは http://www.ietf.org/html.charters/atompub-charter.html (英語)などを参照してください。

はてなブックマークAtomAPI はオリジナルのアプリケーションからはてなブックマークを操作するためのインターフェースです。はてなブックマークAtomAPIを利用することで、HTMLを解析してパラメーターを組み立てPOSTするといった、いわゆるHTMLスクレイピングのような手法を行うことなしに、専用のAPIインタフェースを使ってアプリケーションを実装することができます。

はてなブックマークにおけるAtomAPI実装の概要

はてなブックマークAtomAPIはRESTをサポートしています。現時点でSOAPはサポートしていません。

HTTP の GET/POST/PUT/DELETE を特定のURIに対して行い、そのリクエストに規定のXML文書を加えて送信することでインタフェースが用意している操作を行うことができます。また、一部の操作はそのレスポンスとして規定のXML文書を返却します。

現時点でAPIがサポートしている操作は以下です。

  • 新規ブックマークの投稿 (PostURI への POST)
  • 投稿したブックマークのタイトル、コメントの変更 (EditURI への PUT)
  • 投稿したブックマークの削除 (EditURI への DELETE)
  • 投稿したブックマークの参照 (EditURI への GET)
  • 最近投稿したブックマークの一覧の取得 (FeedURI への GET)

以下、はてなブックマークAtomAPIの詳細を解説します。

認証

AtomAPIの認証には OAuth 認証 もしくは WSSE認証が利用されます。

OAuth 認証の詳細に関しては、はてなのOAuthを利用する方法を参照してください。はてなブックマーク Atom API では、ブックマーク情報を参照するには read_public 操作 が ブックマークを追加したり、エントリーの情報を変更するには write_public 操作の承認を得ている必要があります。また、プライベートブックマークの情報を参照したり変更したりする場合にはそれぞれ read_private 操作 write_private 操作が必要になります。

WSSE認証の詳細に関しては、はてなサービスにおけるWSSE認証を参照してください。

ルートAtomエンドポイント

はてなブックマークAtomAPIのルートAtomエンドポイントは以下になります。ルートAtomエンドポイントに対しGETリクエストを行うことで、PostURIとFeedURIを取得することができます。

http://b.hatena.ne.jp/atom

リクエスト

GET /atom HTTP/1.1
Host: b.hatena.ne.jp

レスポンス

HTTP/1.1 200 OK
Content-Type: application/x.atom+xml

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://purl.org/atom/ns#">
  <link type="application/x.atom+xml" rel="service.post"
        href="http://b.hatena.ne.jp/atom/post" title="sampleのブックマーク" />
  <link type="application/x.atom+xml" rel="service.feed"
        href="http://b.hatena.ne.jp/atom/feed" title="sampleのブックマーク" />
</feed>

PostURI

PostURIははてなブックマークへブックマークを新規投稿するためのエンドポイントです。POSTメソッドのみをサポートしています。PostURIに対し規定のリクエスト用XML文書をPOSTすることでブックマークの投稿が可能です。

リクエスト用XML文書に記述することができるパラメータは以下です。

  • ブックマークするページのURLをlink要素に(必須)
    • rel属性にrelated
    • type属性にtext/html
    • href属性にブックマークするページのURL
  • ブックマークのコメントをsummary要素に(省略可)
    • type属性にtext/plain

ブックマークするページのURIは、はてな側で正規化されます。

操作が何かしらの理由によって失敗した場合は、正常レスポンスとは異なるステータスコードと、それに合わせたエラーメッセージをHTTPヘッダとして返却します。

ブックマークのタイトルの編集について

PostURI による投稿時はブックマークのタイトルを編集することはできません。タイトルはlink要素に指定したURLから自動取得され設定されます。これは、はてなブックマークにおける各エントリーのタイトルが、全ユーザー共通であることを考慮し、タイトルを変更する場合はすでに設定されているタイトルを一度確認した上で編集を行っていただきたい故の仕様です。

ブックマークの任意のタイトルを編集するアプリケーションを実装する場合は、

  1. PostURI POST でブックマークを投稿
  2. EditURI GET でタイトルを取得
  3. 2. で取得したタイトルを変更したい場合は、EditURI PUT でタイトルを変更

という手順でアプリケーションのユーザーに既存のタイトルを確認させた上で、EditURI にて変更してください。

リクエスト

POST /atom/post HTTP/1.1
Host: b.hatena.ne.jp

<entry xmlns="http://purl.org/atom/ns#">
  <title>dummy</title>
  <link rel="related" type="text/html" href="http://www.example.com/" />
  <summary type="text/plain">サンプルコメントです</summary>
</entry>

レスポンス

  • レスポンスは正常終了時としてHTTPステータス201を返します。
  • サンプルのXXXXはURLにおける末尾の数値部(eid)に置き換えてください。
HTTP/1.1 201 Created
Content-Type: application/x.atom+xml
Location: http://b.hatena.ne.jp/atom/edit/XXXX

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://purl.org/atom/ns#">
  <title>example.com</title>
  <link rel="related" type="text/html" href="http://www.example.com/" />
  <link rel="alternate" type="text/html" href="http://b.hatena.ne.jp/sample/20050407#bookmark-XXXX" />
  <link rel="service.edit" type="application/x.atom+xml" href="http://b.hatena.ne.jp/atom/edit/XXXX" title="example.com" />
  <author>
    <name>sample</name>
  </author>
  <generator url="http://b.hatena.ne.jp/" version="0.1">Hatena::Bookmark</generator>
  <issued>2005-04-07T:18:36:00+9:00</issued>
  <id>tag:hatena.ne.jp,2005:bookmark-sample-XXXX</id>
  <summary type="text/plain">サンプルコメントです</summary>
</entry>

EditURI

EditURIははてなブックマークへ投稿した

  • 特定のブックマークを参照 (GET)
  • タイトル / コメントの編集 (PUT)
  • ブックマークの削除 (DELETE)

を行うためのエンドポイントです。操作が何かしらの理由によって失敗した場合は、正常レスポンスとは異なるステータスコードと、それに合わせたエラーメッセージをHTTPヘッダとして返却します。EditURI は eid での指定のほか、http://b.hatena.ne.jp/atom/edit?url=http%3A%2F%2Fwww.hatena.ne.jp%2F のように対象URLをクエリパラメータで指定することもできます。

リクエスト

GET /atom/edit/XXXX HTTP/1.1
Host: b.hatena.ne.jp

レスポンス

HTTP/1.1 200 OK
Content-Type: application/x.atom+xml

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://purl.org/atom/ns#">
  <title>sampleのブックマーク</title>
  <link rel="related" type="text/html" href="http://www.example.com/" />
  <link rel="alternate" type="text/html" href="http://b.hatena.ne.jp/sample/20050407#bookmark-XXXX" />
  <link rel="service.edit" type="application/x.atom+xml" href="http://b.hatena.ne.jp/atom/edit/XXXX" title="example.com" />
  <author>
    <name>sample</name>
  </author>
  <generator url="http://b.hatena.ne.jp/" version="0.1">Hatena::Bookmark</generator>
  <issued>2005-04-07T:18:36:00+9:00</issued>
  <id>tag:hatena.ne.jp,2005:bookmark-sample-XXXX</id>
  <summary type="text/plain">サンプルコメントです</summary>
</entry>

リクエスト

  • title要素、summary要素は省略可能ですが、いずれか一方は存在している必要があります。
  • タイトルの編集に関しては、先の「ブックマークのタイトルの編集について」を参照ください。
PUT /atom/edit/XXXX HTTP/1.1
Host: b.hatena.ne.jp

<entry xmlns="http://purl.org/atom/ns#">
  <title>Sample Page</title>
  <summary type="text/plain">サンプルです。</summary>
</entry>

※特定のブックマークのURLの置換はEditURIへのPUTではサポートしていません。該当のブックマークの削除+新規投稿で対応してください。

レスポンス

HTTP/1.1 200 OK

リクエスト

DELETE /atom/edit/XXXX HTTP/1.1
Host: b.hatena.ne.jp

レスポンス

HTTP/1.1 200 OK

FeedURI

FeedURIは、投稿されたブックマークのうち最近のエントリをAtomフィードで取得するためのエンドポイントです。GETメソッドのみをサポートしています。

リクエスト

GET /atom/feed HTTP/1.1
Host: b.hatena.ne.jp

レスポンス

"

Perl による WSSE 認証の実装

WSSE認証をPerlで実装する例についてははてなサービスにおけるWSSE認証の同項を参照ください。

変更履歴

  • 2011年8月11日 EditURIのレスポンス中のブックマークのURLが正しくなかったのを修正
  • 2011年1月19日 PostURIでのブックマーク時にURLが正規化される旨を追記
  • 2010年12月21日 FeedURIのレスポンスサンプルを追加
  • 2010年12月13日 認証方式に OAuth を追加して Hatena Developer Center で改めて公開
  • 2010年12月7日 URLを直接指定する形式のEditURIに関する記述を追加
  • 2005年12月12日 はてなブックマーク件数取得APIへのリンクを追加
  • 2005年7月5日 はてなブックマークフィード仕様へのリンクを追加
  • 2005年4月8日 誤字など細かな修正
  • 2005年4月7日 リリース