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

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

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

リソースの追加

リクエスト

リソースの追加を行う場合には,コレクションURIに対してPOSTを行います。エントリリソースを追加する際はbody部分に,追加するリソースをXMLで表現したエントリ文書を記述します。MIMEタイプは"application/atom+xml"または"application/atom+xml;type=entry"を指定します。

メディアリソースを追加する際にバイナリデータをそのまま(エンコードなしで)記述します。

以下にエントリリソース追加のための例をご紹介します。

エントリリソース追加のためのリクエスト例

POST /blog/main HTTP/1.1
Host: example.org
Content-Type: application/atom+xml;type=entry
Content-Length: nnn
Slug: the first snow of this season

<entry xmlns="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app">
  <title>初雪</title>
  <id></id>
  <updated>2007-11-18T10:00:00+09:00</updated>
  <app:edited>2007-11-18T10:00:00+09:00</app:edited>
  <content>今日は寒いです。日本列島の中ではどこかは初雪を観測したところがあるんじゃないかな。</content>
  <author>
    <name>asakura</name>
  </author>
</entry>

Slugヘッダ

また,HTTPヘッダの拡張として,Slugヘッダが用意されています。これは追加されたリソースを参照するためのURIやatom:idなどを生成するために参考にされるものです。どのように使われるかはサーバの実装に依存します。もしかしたら使わない実装もあるかもしれません。実際にはファイル名(メディアリソースの場合)やエントリのタイトルを記述してリクエストを出すことが想定されているようです。

SlugヘッダはHTTPヘッダの一部であるため,日本語を記述する場合はエンコードしなければなりません。UTF-8で記述した文字列をさらに%-エンコーディングした文字列を利用します。

レスポンス

成功した場合の帰り値は必ず201 Createdになります。このとき,生成されたエントリ(=メンバリソース)のURIがHTTPのLocationヘッダに記述されて返ってきます。そして,body部分には生成されたエントリの内容が返ります。

メディアリソースを追加した場合は,メディアリンクエントリのURIがLocationヘッダに記載され,メディアリンクエントリの内容がbody部分に返ります。

エントリリソース追加のレスポンス例

HTTP/1.1 201 Created
Date: Sat, 18 Nov 2007 10:10:23 JST
Content-Length: XXX
Content-Type: application/atom+xml;type=entry;charset="utf-8"
Location: http://example.org/blog/main/2

<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-18T10:00:00+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>

返ってくるエントリはPOSTした際のエントリの内容と異なるかもしれません(メディアリンクエントリが返る場合については,エントリの内容は自動生成されています)⁠

特にサーバはatom:id要素やatom:updated要素などの内容について,リソース管理上の観点からサーバ側でPOSTしたときの内容から書き換える可能性があります。また,クライアント側が指定しなかった要素,属性などが追加されたり,指定した要素,属性などが削除されたりすることもあります。こういったサーバ側の書き換えは仕様上許されています。

メンバリソースURIの取得

今後,エントリを編集する場合は,返ってきたエントリの中にあるatom:link要素のうちrel属性値がeditであるURIを使います。

メディアリンクエントリが返ってくる場合も同様で,メディアリンクエントリを編集する場合はatom:link要素のうち,rel="edit"である要素のURIを使います。POSTしたメディアリソースを編集する場合は,atom:link要素のうち,rel="edit-media"である要素のURIを使います。このURIがない場合はメディアリソースが編集できないということになります。

表2にメンバリソースURIをどこから取得したら良いかについてまとめてみました。

通常のエントリリソースを追加した場合は,表中のA.のみが対象になります。

メディアリソースを追加した場合は,メディアリンクエントリとメディアリソースが生成されますので,表中のA.,B.,C.全てが対象になります。

表2 メンバリソースURIとその記載される場所の対応表

メンバリソースURI出現条件記載されている場所
A.生成されたエントリリソースURIMUSTLocationヘッダ
SHOULDatom:link要素(rel="edit")
B.生成されたメディアリソースを参照するためのURIMUSTatom:content要素のsrc属性
C.生成されたメディアリソースURISHOULDatom:link 要素(rel="edit-media")

AtomPubの仕様ではatom:link要素(rel="edit"及びrel="edit-media")は記載されるべき(SHOULD)となっており,含まれない場合もあります。このため,エントリリソースを登録した場合のレスポンスにatom:link要素(rel="edit")が含まれないときはLocationヘッダからエントリリソースURIを取得することになります。

メディアリソースをPOSTした場合もメディアリンクエントリはLocationヘッダで必ず返されます。そして,メディアリンクエントリの場合,必ずatom:content要素がsrc属性にURIを伴って記載されます。しかし,これはメディアリソースURIとは限りません。メディアとして参照できるキャッシュであったり,他のネットワーク上にあるサーバを指していることもあります。ですからメディアリソースURIは必ずatom:link要素(rel="edit-media")に記載されているものを使用します。

著者プロフィール

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

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

コメント

コメントの記入