メインコンテンツまでスキップ

はてなフォトライフAtomAPI

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

本ドキュメントははてなフォトライフにおける AtomAPI 実装を解説するものです。

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

AtomAPI とは​

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

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

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

はてなフォトライフにおけるAtomAPI実装の概要​

はてなフォトライフAtomAPIはRESTをサポートしています。SOAPはサポートしていません。ユーザー認証は OAuth もしくは WSSE により行います。

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

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

  • 新規写真の投稿 (PostURI への POST)
  • 投稿した写真のタイトルの変更 (EditURI への PUT)
  • 投稿した写真の削除 (EditURI への DELETE)
  • 投稿した写真の参照 (EditURI への GET)
  • 最近投稿した写真の一覧の取得 (FeedURI への GET)

以下、はてなフォトライフAtomAPIの詳細を解説します。

認証​

OAuth​

本 API は OAuth によるユーザー認証に対応しています。 OAuth 認証の詳細に関しては、はてなのOAuthを利用する方法を参照してください。

取得 (GET) には read_private 操作、それ以外 (POST, PUT, DELETE) には write_private 操作の承認を得ている必要があります。

WSSE​

OAuth のかわりに WSSE 認証も利用できます。詳しくははてなサービスにおけるWSSE認証をご覧ください。

PostURI​

PostURIははてなフォトライフへ写真を新規投稿するためのエンドポイントです。POSTメソッドのみをサポートしています。PostURIに対し規定のリクエスト用XML文書をPOSTすることで写真の投稿が可能です。写真データBase64エンコードしてリクエスト用XML文書に記述します。また、Dublin Coreモジュールのdc:subject要素を追加することにより、ファルダ名を指定してアップロードすることができます。

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

  • 写真のタイトルをtitle要素のテキストに
  • 写真データをcontent要素に
    • type属性に画像のContent-Type(例: image/jpeg)
    • mode属性はbase64
    • テキストにBase64エンコードされた画像データ文字列
  • アップロード先のフォルダ名をdc:subject要素に
    • 指定されたフォルダが存在しない場合は、自動的に作成されます。
  • アップロードツール名をgenerator要素に
    • フォトライフの設定画面で、アップロードツール毎のフォルダ振り分けの設定ができます。

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

リクエスト​

POST /atom/post

<entry xmlns="http://purl.org/atom/ns#">
  <title>Sample</title>
  <content mode="base64" type="image/jpeg">/9j/2wCEAAQDAwQDAw.../9n/AA==</content>
</entry>

レスポンス​

  • レスポンスは正常終了時としてHTTPステータス201を返します。
  • レスポンスXML文書はHatena XML Namespaceによって拡張されています。
  • サンプルのXXXXXXXXXXXXXXは画像のURLにおける末尾の数値部に置き換えてください。
  • サンプルのYYYYYYは画像をアップロードした写真があるフォルダ名に置き換えてください。
201 Created
Content-Type: application/x.atom+xml
Location: http://f.hatena.ne.jp/atom/edit/XXXXXXXXXXXXXX

<?xml version="1.0" encoding="utf-8"?>

<entry xmlns="http://purl.org/atom/ns#" xmlns:hatena="http://www.hatena.ne.jp/info/xmlns#">
  <title>Sample</title>
  <link rel="alternate" type="text/html" href="http://f.hatena.ne.jp/naoya/XXXXXXXXXXXXXX"/>
  <link rel="service.edit" type="application/x.atom+xml" href="http://f.hatena.ne.jp/atom/edit/XXXXXXXXXXXXXX" title="Sample"/>
  <issued>2005-01-14T17:01:29+09:00</issued>
  <author>
    <name>naoya</name>
  </author>
  <generator url="http://f.hatena.ne.jp/" version="1.0">Hatena::Fotolife</generator>
  <dc:subject xmlns:dc="http://purl.org/dc/elements/1.1/">YYYYYY</dc:subjetct>
  <id>tag:hatena.ne.jp,2005:fotolife-naoya-XXXXXXXXXXXXXX</id>
  <hatena:imageurl>http://f.hatena.ne.jp/images/fotolife/n/naoya/XXXXXXXX/XXXXXXXXXXXXXX.jpg</hatena:imageurl>
  <hatena:imageurlsmall>http://f.hatena.ne.jp/images/fotolife/n/naoya/XXXXXXXX/XXXXXXXXXXXXXX_m.gif</hatena:imageurlsmall>
  <hatena:syntax>f:id:naoya:XXXXXXXXXXXXXX:image</hatena:syntax>
</entry>

EditURI​

EditURIははてなフォトライフへ投稿した

  • 特定の写真エントリのフィードを参照 (GET)
  • 写真の編集 (PUT)
  • 写真の削除 (DELETE)

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

リクエスト​

GET /atom/edit/XXXXXXXXXXXXXX

レスポンス​

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

<?xml version="1.0" encoding="utf-8"?>

<entry xmlns="http://purl.org/atom/ns#" xmlns:hatena="http://www.hatena.ne.jp/info/xmlns#">
  <title>Sample</title>
  <link rel="alternate" type="text/html" href="http://f.hatena.ne.jp/naoya/XXXXXXXXXXXXXX"/>
  <link rel="service.edit" type="application/x.atom+xml" href="http://f.hatena.ne.jp/atom/edit/XXXXXXXXXXXXXX" title="Sample"/>
  <issued>2005-01-14T17:01:29+09:00</issued>
  <author>
    <name>naoya</name>
  </author>
  <id>tag:hatena.ne.jp,2005:fotolife-naoya-XXXXXXXXXXXXXX</id>
  <hatena:imageurl>http://f.hatena.ne.jp/images/fotolife/n/naoya/XXXXXXXX/XXXXXXXXXXXXXX.jpg</hatena:imageurl>
  <hatena:imageurlsmall>http://f.hatena.ne.jp/images/fotolife/n/naoya/XXXXXXXX/XXXXXXXXXXXXXX_m.gif</hatena:imageurlsmall>
  <hatena:syntax>f:id:naoya:XXXXXXXXXXXXXX:image</hatena:syntax>
</entry>

リクエスト​

PUT /atom/edit/XXXXXXXXXXXXXX

<entry xmlns="http://purl.org/atom/ns#">
  <title>My Photo</title>
</entry>

※特定の画像エントリの画像データの置換はEditURIへのPUTではサポートしていません。該当のエントリの削除+新規投稿で対応してください。

レスポンス​

200 OK

リクエスト​

DELETE /atom/edit/XXXXXXXXXXXXXX

レスポンス​

200 OK

FeedURI​

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

フィードに含まれるエントリの件数は、はてなフォトライフでのユーザー設定によって決定されます。

リクエスト​

GET /atom/feed

レスポンス​

はてなフォトライフがフィードしているAtomフィードと同様の結果を返します。ここでは省略します。