スマートフォン用の表示で見る

はてなブックマークAtomAPI

はてな

はてなブックマークAtomAPI

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

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

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

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

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

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

変更履歴

AtomAPI とは

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

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

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

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

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

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

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

以下、はてなブックマーク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文書に記述することができるパラメータは以下です。

操作が何かしらの理由によって失敗した場合は、正常レスポンスとは異なるステータスコードと、それに合わせたエラーメッセージ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ははてなブックマークへ投稿した

を行うためのエンドポイントです。操作が何かしらの理由によって失敗した場合は、正常レスポンスとは異なるステータスコードと、それに合わせたエラーメッセージ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フィードと同様の結果を返します。ここでは省略します。

目次