Hatena Blog Tags

はてなブックマークAtomAPI

(はてな)
はてなぶっくまーくあとむえーぴー


このページは古い情報を掲載しています

このページの情報は更新されていません。新しい情報は「はてなブックマークAtomAPI - Hatena Developer Center」に移転しました。

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

本ドキュメントははてなブックマークにおける AtomAPI 実装を解説するものです。主にはてなスタッフがその作成と更新を行っています。

Atomプロジェクトが定めるAtomAPI仕様 http://www.ietf.org/html.charters/atompub-charter.html (英語)は現時点でドラフト段階です。それに伴い本ドキュメントおよびはてなブックマークの AtomAPI 実装は変更される可能性があります。

変更履歴

  • 2005年12月12日 はてなブックマーク件数取得APIへのリンクを追加
  • 2005年7月5日 はてなブックマークフィード仕様へのリンクを追加
  • 2005年4月8日 誤字など細かな修正
  • 2005年4月7日 リリース

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の詳細を解説します。

WSSE認証

AtomAPIの認証にはWSSE認証が利用されます。はてなブックマークAtomAPIの利用にはWSSE認証が必須です。WSSE認証の詳細に関しては、はてなフォトライフAtomAPIのWSSEの項 (http://d.hatena.ne.jp/keyword/%a4%cf%a4%c6%a4%ca%a5%d5%a5%a9%a5%c8%a5%e9%a5%a4%a5%d5AtomAPI?kid=88110#wsse) を参照してください。

ルートAtomエンドポイント

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

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

リクエスト

GET /atom

レスポンス

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

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

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

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

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

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

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

リクエスト

POST /atom/post

<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)に置き換えてください。
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#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ヘッダとして返却します。

リクエスト

GET /atom/edit/XXXX

レスポンス

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#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

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

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

レスポンス

200 OK

リクエスト

DELETE /atom/edit/XXXX

レスポンス

200 OK

FeedURI

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

リクエスト

GET /atom/feed

レスポンス

はてなブックマークがフィードしているAtomフィードと同様の結果を返します。ここでは省略します。

Perl による WSSE 認証の実装

WSSE認証をPerlで実装する例についてははてなフォトライフAtomAPIの同項(http://d.hatena.ne.jp/keyword/%a4%cf%a4%c6%a4%ca%a5%d5%a5%a9%a5%c8%a5%e9%a5%a4%a5%d5AtomAPI?kid=88110#wsseperl)を参照ください。

このタグの解説についてこの解説文は、すでに終了したサービス「はてなキーワード」内で有志のユーザーが作成・編集した内容に基づいています。その正確性や網羅性をはてなが保証するものではありません。問題のある記述を発見した場合には、お問い合わせフォームよりご連絡ください。

ネットで話題

もっと見る