たけまる / Atom Publishing Protocol のメモ

■ 名前空間

http://www.w3.org/2007/app

■ コレクションとリソース

         Collection
              1
              |
      -----------------
     |                 |
     *                 *
Entry Resource    Media Resource
                       1
                       |
                       1
                Media Link Entry

- コレクションとは階層のないディレクトリのようなもの

■ リソースの分類

       Member Resources
              |
      -----------------
     |                 |
Entry Resources     Media Resources
     |
Media Link Entry

リソース名	表現
Entry Resource	エントリ文書
Media Resource	バイナリデータなど
Media Link Entry	エントリ文書 (//content/@src は Media Resource へのリンク)

■ 文書 (XML表現)

	ルート要素	メディアタイプ	ファイル拡張子
フィード文書	<feed>	application/atom+xml;type=feed	.atom
エントリ文書	<entry>	application/atom+xml;type=entry	.atom
サービス文書	<service>	application/atomsvc+xml	.atomsvc
カテゴリ文書	<categories>	application/atomcat+xml	.atomcat

- フィード文書は，エントリ文書を列挙する
- サービス文書は，カテゴリ文書を含む

■ サービス文書の取得

Client                                     Server
  |                                           |
  |  1.) GET to Service Document              |
  |------------------------------------------>|
  |                                           |
  |  2.) 200 OK, Service Document             |
  |<------------------------------------------|
  |                                           |

■ リソースの列挙 (フィード文書の取得)

Client                          Server
  |                                |
  |  1.) GET to Collection URI     |
  |------------------------------->|
  |                                |
  |  2.) 200 OK, Atom Feed Doc     |
  |<-------------------------------|
  |                                |

■ リソースの作成

Client                                     Server
  |                                           |
  |  1.) POST to URI of Collection            |
  |------------------------------------------>|
  |                                           |
  |  2.) 201 Created                          |
  |      Location: Member Entry URI           |
  |<------------------------------------------|
  |                                           |

- Entry Resource を POST すると，Entry Resource が返る
- Media Resource を POST すると，それへのリンクを持った Media Link
  Entry が返る
- サーバは，POST されたリソースを変更してもよい (id, updated など
  はよく変更される)

■ リソースの更新

Client                                     Server
  |                                           |
  |  1.) GET to Member URI                    |
  |------------------------------------------>|
  |                                           |
  |  2.) Member Representation                |
  |<------------------------------------------|
  |                                           |

Client                                     Server
  |                                           |
  |  1.) PUT to Member URI                    |
  |------------------------------------------>|
  |                                           |
  |  2.) 200 OK                               |
  |<------------------------------------------|

- GET でリソースを取得してから，変更を加えること

■ サービス文書の例

<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://purl.org/atom/app#"
         xmlns:atom="http://www.w3.org/2005/Atom">
  <workspace>
    <atom:title>Main Site</atom:title>

    <collection href="http://example.org/reilly/main" >
      <atom:title>My Blog Entries</atom:title>
      <categories href="http://example.com/cats/forMain.cats" />
    </collection>

    <collection href="http://example.org/reilly/pic" >
      <atom:title>Pictures</atom:title>
      <accept>image/*</accept>
    </collection>
  </workspace>

  <workspace>
    <atom:title>Side Bar Blog</atom:title>

    <collection href="http://example.org/reilly/list" >
      <atom:title>Remaindered Links</atom:title>
      <accept>application/atom+xml;type=entry</accept>
      <categories fixed="yes">
        <atom:category scheme="http://example.org/extra-cats/" term="joke" />
        <atom:category scheme="http://example.org/extra-cats/" term="serious" />
      </categories>
    </collection>
  </workspace>
</service>

- app:workspace の存在意義は不明
- app:collection の href 属性は，コレクションの URI を表す
- app:categories 要素では，カテゴリを列挙することもできるし，カテ
  ゴリ文書の URI を指定してもよい
- app:accept 要素は，生成可能なリソースのメディアタイプである

■ カテゴリ文書の例

<?xml version="1.0" ?>
<app:categories xmlns:app="http://purl.org/atom/app#"
                xmlns="http://www.w3.org/2005/Atom"
                fixed="yes" scheme="http://example.com/cats/big3">
  <category term="animal" />
  <category term="vegetable" />
  <category term="mineral" />
</app:categories>

- app:categories 要素の fixed 属性は，カテゴリが固定されている (リ
  ストにないカテゴリを受け付けない) ことを表す

■ フィード文書 (コレクション) のページ付け

<feed xmlns="http://www.w3.org/2005/Atom">
  <link rel="first" href="http://example.org/entries/go" />
  <link rel="previous" href="http://example.org/entries/go" />
  <link rel="next" href="http://example.org/entries/3" />
  <link rel="last" href="http://example.org/entries/10" />
  ...
</feed>

- サーバはフィード文書を複数ページに分割できる

■ app:control, app:draft 要素

リソースの公開範囲を制御するために用いられる．

<entry xmlns:app="http://purl.org/atom/app#"
       xmlns="http://www.w3.org/2005/Atom">
  <app:control>
    <app:draft>yes</app:darft>
  </app:control>
</entry>

- app:draft 要素が yes であれば，非公開となる (編集中の記事などで用いる)