はてなフォトライフ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フィードと同様の結果を返します。ここでは省略します。
CPANモジュール XML::Atom::Client を利用した投稿
CPANモジュールのXML::Atom::ClientはAtomAPIクライアントを実装するための、WSSE認証やリクエスト、レスポンスに必要なXML文書の組み立てなどを抽象化したモジュールです。 XML::Atom::Clientを用いて、はてなフォトライフに任意の画像をアップロードするサンプルコードは以下のようになります。
#!/usr/local/bin/perl
use strict;
use warnings;
use FileHandle;
use XML::Atom::Entry;
use XML::Atom::Client;
my $PostURI = 'http://f.hatena.ne.jp/atom/post';
my $username = shift or die "need username";
my $password = shift;
my $api = XML::Atom::Client->new;
$api->username($username);
$api->password($password);
my $file = shift;
local $/; # slurp mode
my $fh = FileHandle->new($file)
or die "cannnot open $file: $!";
my $image = $fh->getline;
my $entry = XML::Atom::Entry->new;
$entry->content($image);
$entry->content->type('image/jpeg');
$entry->title('Sample image for AtomAPI');
my $EditURI = $api->createEntry($PostURI, $entry) or
die $api->errstr;
print $EditURI;
XML::Atom::Client はWSSE認証を抽象化しているため、username/passwordメソッドでそれぞれをセットするだけで認証を通過できます。また、XML文書の組み立てはXML::Atom::Entryインスタンスを生成して行い、それを最後にXML::Atom::Clientインスタンスに渡せば完了です。 このスクリプトはコマンドラインから実行し、
$ perl atompost.pl hatena hatena ./sample.jpg
として第3引数に画像ファイルを指定します。画像データのBase64エンコードもXML::Atom::Entryが抽象化しているので、プログラマは特に気にする必要はありません。
参考
- Atom Publishing Format and Protocol (atompub) -
- AtomEnabled / Developers / API / Atom API Spec
- TypePad Atom API
- blog.livedoor.com Atom API Spec
- LWP::Authen::Wsse
- XML::Atom
- WebService::Hatena::Fotolife (Perl によるクライアント実装)
変更履歴
- 2013年10月3日 OAuth に対応
- 2008年10月30日 dc:subject要素によるフォルダ指定、generator要素によるフォルダ振り分けに対応
- 2005年4月7日 仕様書参照先のURLを http://www.ietf.org/html.charters/atompub-charter に変更
- 2005年1月18日 リリース