Web APIの次世代標準プロトコル「Atom Publishing Protocol」

第3回 リソースの操作を追う

この記事を読むのに必要な時間:およそ 7 分

リソースの更新

リクエスト

リソースの更新はPUTを使って行うことができます。PUTのbody部分には,更新を行う内容を記載します。エントリリソースの場合は,変更したい内容をXMLであるエントリ文書として表現します。基本的には表現されたエントリ文書でそのまま更新されることになります。ただし,サーバ側の判断で許可されていない要素や内容についてはクライアント側のリクエスト通り更新されません。また,クライアント側は変更されていない要素を消失しないよう,先にGETしたエントリを必要な部分だけ書き換えてPUTするのが良いでしょう。

メディアリソースを更新する場合は,PUTリクエストのbody部分にバイナリデータを記述します。

以下にエントリリソースを更新するPUTの例をご紹介します。この例では,atom:conten要素の内容を少し書き換えています。また,編集した時刻(app:edited要素)も少し変更しています。

エントリリソース更新のためのリクエスト例

PUT /blog/main/2 HTTP/1.1
Host: example.org
Content-Type: application/atom+xml;type=entry
Content-Length: XXX

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app">
  <title>初雪</title>
  <id>http://example.org/blog/main/article/73821</id>
  <published>2007-11-18T10:10:21+09:00</published>
  <updated>2007-11-18T10:10:21+09:00</updated>
  <app:edited>2007-11-18T12:10:34+09:00</app:edited>
  <content>今日は寒いです。日本列島の中ではどこかは初雪を観測したところがあるんじゃないかな。・・・と思ったら本当に降ってたみたいですね。</content>
  <link rel="alternate" type="text/html" href="http://example.org/blog/main/article/73821"/>
  <link rel="edit" href="http://example.org/blog/main/2"/>
  <author>
    <name>asakura</name>
  </author>
</entry>

この結果,atom:content要素とapp:edited要素はクライアント側の指定した内容に書き換わることを期待しています。

レスポンス

成功した場合,200Okが返ります。

エントリリソース更新のレスポンス例

HTTP/1.1 200 Ok
Date: Sat, 18 Nov 2007 10:35:11 JST
Content-Length: XXX
Content-Type: application/atom+xml;type=entry;charset="utf-8"

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app">
  <title>初雪</title>
  <id>http://example.org/blog/main/article/73821</id>
  <published>2007-11-18T10:10:21+09:00</published>
  <updated>2007-11-18T10:35:08+09:00</updated>
  <app:edited>2007-11-18T12:10:34+09:00</app:edited>
  <content>今日は寒いです。日本列島の中ではどこかは初雪を観測したところがあるんじゃないかな。・・・と思ったら本当に降ってたみたいですね。</content>
  <link rel="alternate" type="text/html" href="http://example.org/blog/main/article/73821"/>
  <link rel="edit" href="http://example.org/blog/main/2"/>
  <author>
    <name>asakura</name>
  </author>
</entry>

この例では,期待どおりapp:editedとatom:content要素が書き換わっています。

また,atom:updatedやatom:published要素はサーバ側が適宜書き換えてくれていますが,これは実装依存です。atom:updatedやatom:published要素についても,クライアント側の指定どおりに書き換えてくれるサーバがあるかもしれません。

他の名前空間に属する要素の扱い

エントリリソースを更新する場合,エントリ文書をPUTします。エントリ文書は,atom:entry要素をルート要素としますが,決められた要素以外にもXML名前空間の仕組みを使って他の名前空間に属する要素を記載することもできます。ただし,実際にエントリとして保存するかどうかはサーバの実装に任されています。

また,サーバからリソースを取得した場合,他の名前空間に属する要素が入っている場合もあります。このときには未知のものであってもクライアントはその要素を保持し,そのままPUTリクエストのbody部分に記載をすべきです。これは編集によるデータの消失を防ぐ観点から重要なことです。

PUTした内容の扱い

エントリリソースを更新する場合,POSTの時と同様にPUTで送付したエントリ文書がそのまま反映されるとは限りません。例えばatom:id要素はそのエントリに対してユニークなものであることからクライアント側から書き換えができない場合がほとんどでしょう。このような要素を更新するためにクライアント側は内容を書き換えてPUTを行ったとしても,無視されて処理が実行されることになるでしょう。

リソースの削除

リクエスト

リソースの削除は,メンバリソースのURIに対してDELETEメソッドを適用します。多くの場合,何らかの方法(Basic認証やWSSE認証など)で認証され,削除権限があれば許可されるでしょう。削除する対象がメディアリンクエントリである場合はメディアリソースも,対象がメディアリソースである場合は,メディアリンクエントリも同時に削除されることが多いでしょう(厳密には実装依存です)⁠

リソース削除のためのリクエスト例

DELETE /blog/main/2 HTTP/1.1
Host: example.org

レスポンス

成功した場合は200 OKが返ります。失敗した場合は,理由に応じたHTTPのエラーが返ることになります。

リソース削除のレスポンス例

HTTP/1.1 200 Ok
Date: Sun, 18 Nov 2007 23:50:13 JST

認証

本連載では認証については全く触れてきませんでした。しかし,AtomPubはサーバ上のリソースを編集することができるプロトコルです。通常はクライアント側の認証は必須となるでしょう。認証方法についてはAtomPubがどこでどういった使われ方をするかによって様々な選択肢があると思います。IETFのWG内でも議論の過程で様々な意見が出ました。しかし最終的には,⁠最低限HTTP及びHTTPS(TLS)上でのBasic認証が設定できること」というところで仕様を決着させました。ある意味,仕様としては現実解を取ったともいえます。

実際のAtomPubサーバはBasic認証以外の認証をサポートすることも多いと思います。色々な方法があると思いますが,AtomPubはREST志向のプロトコルですので,一回一回のCRUD操作で認証が走る方法(ステートレス)が望ましいでしょう。

エラー

AtomPubはHTTPベースのプロトコルですので,エラー時には基本的にHTTPのエラーで表現されます。サーバ側が400番台と500番台のエラーを返すときには人間が可読なエラーメッセージを含めるように実装することが求められていますが詳細までは決められていません。

まとめ

駆け足でAtomを見てきましたが,表層はすごく理解しやすいプロトコルだとお感じになられたのではないでしょうか?

AtomPubの本質はREST的なCRUD操作をAtomフィードを使って定義したところにあります。これさえ押さえてしまえば理解したも同然です。しかし,実際にRFCを読み深めていくと,サーバの実装に任されている部分が多いプロトコルであるとお気づきになるでしょう。このためサーバの設計者は(クライアントの設計者も)細かなところで難しい判断を迫られることになるかもしれません。今後は,様々な実装が出てくることで,実装経験が蓄積されていく(Best Current Practice)と思われます。またそれとともに新しい仕様がIETF draftとして出てくると予想されます。

必ずしも全てのwebサービスがこのコレクションとメンバリソースのモデルに親和性があるわけではありませんが,単純なデータモデルですから大半のwebサービスには適用できると思います。また,メンバリソースに関連するハイパーリンクをatom:link要素として表現しているのもwebの概念をうまく利用し,拡張性を豊かなものにしていると思います。是非皆様もAtomPubを利用してみてください。

次回は最後の連載になります。著者を交代しまして,弊社坂野のほうからサンプルプログラムによるAtomサーバへのアクセス事例をご紹介しましょう。

著者プロフィール

朝倉浩志(あさくらひろし)

NTTコミュニケーションズ 先端IPアーキテクチャセンタ リサーチエンジニア。上位層プロトコル及びWebテクノロジの技術開発に取り組む。

コメント

コメントの記入