Atom 1.0: protokol

Na formát Atom 1.0 navazuje publikační protokol Atom (Atom Publication Protocol čili APP, dříve též Atom API). Jedná se o obecný aplikační protokol určený k publikování a editaci webových zdrojů. Hlavními standardy, na nichž APP staví, jsouHTTP 1.1 a XML 1.0. Protokol APP je navržen v souladu s architekturou webu, jejíž základní sémantické prvky – URI (případně IRI), zdroj a reprezentaci – doplňuje o dva nové pojmy:

• Kolekce je zvláštní zdroj obsahující sadu URI svých členů, webových zdrojů. Reprezentací kolekce je dokument ve formátu Atom 1.0.
• Introspekční dokument je dokument popisující jednu nebo více kolekcí. Každý webový server může mít svůj introspekční dokument. Pro reprezentaci introspekčního dokumentu APP zavádí zvláštní formát.

Některé současné protokoly vytvořené nad HTTP (např. XML-RPC či SOAP) si vystačí s metodou POST, čímž se připravují o důležité výhody webové architektury. Atom 1.0 přirozeným způsobem využívá všechny hlavní metody protokolu HTTP. GET slouží k načtení reprezentace, POSTem se vytváří nový zdroj, PUT aktualizuje existující zdroj a DELETE zdroj odstraňuje.

Každá kolekce smí obsahovat pouze zdroje jednoho typu. Členy mohou být buď položky formátu Atom (textový obsah, HTML či XHTML, typ entry), nebo libovolné samostatné soubory (typ media). Položky prvního typu musí obsahovat element <link href=„URI“ rel=„edit“> s URI, jež slouží k editaci tohoto zdroje. Členové typu media musí obsahovat element <content src="URI"> s odkazem na samotný zdroj pouze pro čtení. Nepovinný element <link href=„URI“ rel=„edit“> může poskytnout další URI pro editaci zdroje.

Možné operace protokolu Atom jsou tyto:

1. Načtení introspekčního dokumentu: GET na URI introspekčního dokumentu. Vrací introspekční dokument, který může obsahovat popis jedné nebo více „pracovních ploch” (workspace). Pracovní plocha je volné seskupení kolekcí; může obsahovat jednu či více kolekcí, přičemž tatáž kolekce se smí vyskytovat ve více pracovních plochách.

<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://purl.org/atom/app#">
  <workspace title="Main Area" >
    <collection title="Blog Entries"
      href="http://example.org/blog" >

      <member-type>entry</member-type>
      <list-template>http://example.org/blog/{index}</list-template>
    </collection>
    <collection title="Pictures"
      href="http://example.org/pic" >
      <member-type>media</member-type>

      <list-template>http://example.org/pic/{index}</list-template>
    </collection>
  </workspace>
</service> 

2. Načtení seznamu členů kolekce: GET na URI kolekce. Vrací dokument ve formátu Atom 1.0. Zde je příklad kolekce typu  entry.

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  [...]
  <entry>
    <title>Example entry</title>
    <link href="http://example.org/blog/1" rel="edit"/>

    <id>urn:uuid:1225c695-ffb8-4ebb-aaaa-80da354efa6a</id>
    <updated>2006-01-28T10:30:00Z</updated>
    <summary>A brief description</summary>
    <content type="text" xml:lang="en">

      The full text.
    </content>
  </entry>
  [...]
</feed> 

3. Vytvoření nového zdroje: POST na URI kolekce. Tělo požadavku obsahuje reprezentaci nového člena kolekce. Jméno zdroje je vytvořeno dynamicky s pomocí šablony v elementu list-template v introspekčním dokumentu. Vrací se návratový kód 201 Created a hlavička Location s URI nového zdroje. Nový člen musí být typu ( entry nebo media), který kolekce akceptuje. Zde je příklad těla požadavku přidávajícího do kolekce typu media nový obrázek.

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">

  <title>A picture.</title>
  <link rel="edit"
    href="http://example.org/pic/edit/1.png"/>
  <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-568596895695</id>
  <updated>2006-01-28T10:30:00Z</updated>

  <summary>The picture description</summary>
  <content type="image/png"
    src="http://example.org/pic/readonly/1.png"/>
</entry> 

4. Načtení zdroje: GET na URI člena kolekce. Vrací reprezentaci daného zdroje.

5. Aktualizace zdroje: PUT na URI člena kolekce. Tělo požadavku obsahuje aktualizovanou reprezentaci člena kolekce. Při úspěchu vrací návratový kód 200 Ok.

6. Odstranění zdroje: DELETE na URI člena kolekce. Při úspěchu vrací návratový kód 200 Ok.

To je vše, co se dá dělat s protokolem APP. Rozsahem malý protokol se výborně hodí ke psaní a aktualizování novinkových serverů, blogů a podobných webů. Pomocí APP bude možné s minimálním úsilím vytvořit jednoduchý systém pro správu obsahu. Webový server vybavený modulem podporujícím APP a introspekčním dokumentem bude moci být pohodlně aktualizován grafickým klientem APP. Umím si představit řadu případů, kde bych takovou možnost rád využil.

Implementace APP jsou zatím v plenkách; už vzhledem k tomu, že protokol Atom je zatím pouze draft a nelze vyloučit, že se ještě bude měnit. Podle původních plánů měl být protokol APP dokončen a předložen IETF ke schválení koncem roku 2005, ale patří k povaze věcí, že se zpožďují. Současný draft verze 0.7 je platný do června a je pravděpodobné, že by už mohl být nahrazen konečnou verzí. Pak by letošní rok mohl ověřit, do jaké míry se možnosti protokolu Atom shodují s potřebami uživatelů.