本ドキュメントははてなブックマークにおける AtomAPI 実装を解説するものです。
はてなブックマークの AtomAPI 実装は The Atom Publishing Protocol 草案に基づいたものです。今後本ドキュメント及びはてなブックマークの AtomAPI 実装は RFC 5023 - The Atom Publishing Protocol に従う形へ変更される可能性があります。
AtomAPI はウェブリソースを出版、編集するためのアプリケーション・プロトコル仕様です。はてなブックマークのAtomAPIを利用することで、開発者ははてなブックマークにブックマークを参照、投稿、編集、削除したりを行うオリジナルのアプリケーションを作成することができます。
AtomAPIについて詳しくは http://www.ietf.org/html.charters/atompub-charter.html (英語)などを参照してください。
はてなブックマークAtomAPI はオリジナルのアプリケーションからはてなブックマークを操作するためのインターフェースです。はてなブックマークAtomAPIを利用することで、HTMLを解析してパラメーターを組み立てPOSTするといった、いわゆるHTMLスクレイピングのような手法を行うことなしに、専用のAPIインタフェースを使ってアプリケーションを実装することができます。
はてなブックマークAtomAPIはRESTをサポートしています。現時点でSOAPはサポートしていません。
HTTP の GET/POST/PUT/DELETE を特定のURIに対して行い、そのリクエストに規定のXML文書を加えて送信することでインタフェースが用意している操作を行うことができます。また、一部の操作はそのレスポンスとして規定のXML文書を返却します。
現時点でAPIがサポートしている操作は以下です。
以下、はてなブックマークAtomAPIの詳細を解説します。
AtomAPIの認証には OAuth 認証 もしくは WSSE認証が利用されます。
OAuth 認証の詳細に関しては、はてなのOAuthを利用する方法を参照してください。はてなブックマーク Atom API では、ブックマーク情報を参照するには read_public 操作 が ブックマークを追加したり、エントリーの情報を変更するには write_public 操作の承認を得ている必要があります。また、プライベートブックマークの情報を参照したり変更したりする場合にはそれぞれ read_private 操作 write_private 操作が必要になります。
WSSE認証の詳細に関しては、はてなサービスにおけるWSSE認証を参照してください。
はてなブックマークAtomAPIのルートAtomエンドポイントは以下になります。ルートAtomエンドポイントに対しGETリクエストを行うことで、PostURIとFeedURIを取得することができます。
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ははてなブックマークへブックマークを新規投稿するためのエンドポイントです。POSTメソッドのみをサポートしています。PostURIに対し規定のリクエスト用XML文書をPOSTすることでブックマークの投稿が可能です。
リクエスト用XML文書に記述することができるパラメータは以下です。
ブックマークするページのURIは、はてな側で正規化されます。
操作が何かしらの理由によって失敗した場合は、正常レスポンスとは異なるステータスコードと、それに合わせたエラーメッセージをHTTPヘッダとして返却します。
PostURI による投稿時はブックマークのタイトルを編集することはできません。タイトルはlink要素に指定したURLから自動取得され設定されます。これは、はてなブックマークにおける各エントリーのタイトルが、全ユーザー共通であることを考慮し、タイトルを変更する場合はすでに設定されているタイトルを一度確認した上で編集を行っていただきたい故の仕様です。
ブックマークの任意のタイトルを編集するアプリケーションを実装する場合は、
という手順でアプリケーションのユーザーに既存のタイトルを確認させた上で、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/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ははてなブックマークへ投稿した
を行うためのエンドポイントです。操作が何かしらの理由によって失敗した場合は、正常レスポンスとは異なるステータスコードと、それに合わせたエラーメッセージを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>
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は、投稿されたブックマークのうち最近のエントリをAtomフィードで取得するためのエンドポイントです。GETメソッドのみをサポートしています。
GET /atom/feed HTTP/1.1 Host: b.hatena.ne.jp
HTTP/1.1 200 OK Content-Type: application/xml <?xml version="1.0" encoding="utf-8"?> <feed xmlns="http://purl.org/atom/ns#" xml:lang="ja"> <title>sample のブックマーク</title> <id>tag:hatena.ne.jp,2005:bookmark-sample</id> <link type="text/html" rel="alternate" href="http://b.hatena.ne.jp/sample/"/> <link rel="service.post" type="application/x.atom+xml" href="http://b.hatena.ne.jp/atom/post" title="sample のブックマーク"/> <link rel="next" type="application/x.atom+xml" href="http://b.hatena.ne.jp/sample/atomfeed?of=20"/> <entry> <title>はてなスタッフのブックマーク拝見！ - 営業マン編「仕事の様々なシーンでフル活用」</title> <link type="text/html" rel="related" href="http://b.hatena.ne.jp/guide/staff_bookmark_03"/> <link type="text/html" rel="alternate" href="http://b.hatena.ne.jp/sample/20090410#bookmark-12884905"/> <link type="application/x.atom+xml" rel="service.edit" title="はてなスタッフのブックマーク拝見！ - 営業マン編「仕事の様々なシーンでフル活用」" href="http://b.hatena.ne.jp/atom/edit/12884905"/> <author> <name>sample</name> </author> <summary></summary> <id>tag:hatena.ne.jp,2005:bookmark-sample-12884905</id> <issued>2009-04-10T18:44:20+09:00</issued> <dc:subject xmlns:dc="http://purl.org/dc/elements/1.1/">はてな</dc:subject> <dc:subject xmlns:dc="http://purl.org/dc/elements/1.1/">インタビュー</dc:subject> <dc:subject xmlns:dc="http://purl.org/dc/elements/1.1/">はてなブックマーク</dc:subject> </entry> <entry> <title>はてな</title> <link type="text/html" rel="related" href="http://www.hatena.ne.jp/"/> <link type="text/html" rel="alternate" href="http://b.hatena.ne.jp/sample/20090116#bookmark-370"/> <link type="application/x.atom+xml" rel="service.edit" title="はてな" href="http://b.hatena.ne.jp/atom/edit/370"/> <author> <name>sample</name> </author> <summary>はてなのトップページ。</summary> <id>tag:hatena.ne.jp,2005:bookmark-sample-370</id> <issued>2009-01-16T15:50:52+09:00</issued> <dc:subject xmlns:dc="http://purl.org/dc/elements/1.1/">情報収集</dc:subject> <dc:subject xmlns:dc="http://purl.org/dc/elements/1.1/">webサービス</dc:subject> </entry> </feed>
WSSE認証をPerlで実装する例についてははてなサービスにおけるWSSE認証の同項を参照ください。