\chapter{Atom Publishing Protocol}

Az RSS mint formátum már jóval az Atom előtt megjelent, így néhány évnyi tapasztalat összegyűlt a webes megosztás és együttműködés területén, mielőtt megalkották az Atomot. Ebbe a témakörbe tartozik az is, hogyan lehet publikálni egy olyan elemet, amely később egy feedben jelenik majd meg. A blogoknál ez kezdetben egy XML-RPC alapú megoldás volt.

Az Atom nem csupán egy formátum. A készítők szándékosan terveztek hozzá egy protokollt is, az Atom Publishing Protocolt (APP vagy AtomPub), amellyel a szokásos módon manipulálni (elemet hozzáadni, módosítani, törölni) is lehet Atom-feedeket. Az Atom szindikációs formátum és az Atom publikációs protokoll szorosan összetartozik. Az APP az IETF által szabványosított, az RFC  5023 rögzíti. Alapja a HTTP, és az úgynevezett REST alapelveit követi.

\section{REST}

A REST, azaz Representational State Transfer (Reprezentációs állapotátvitel) fogalma a HTTP egyik megalkotójának, Roy Fieldingnek 2000-ben kelt doktori disszertációjában \cite{fielding} jelent meg először, azóta pedig széles körben használatos a hálózatokkal foglalkozó szakemberek körében. Szigorú értelemben véve a REST alapelvei azt körvonalazzák, hogy bizonyos \emph{erőforrásokat} hogyan lehet definiálni és megfogni, megcímezni. Egy szabadabb értelmezésben egy olyan interfészt írhat le, amely domén-specifikus adat átvitelére alkalmas HTTP-n keresztül\footnote{A REST maga nem támaszkodik a HTTP-re, és lehet tervezni olyan egyszerű HTTP-alapú rendszert is, amelyre a REST alapelvei nem teljesülnek, hanem inkább a távoli eljáráshívás (RPC) modellt követi.}, további rétegek nélkül (mint például a SOAP, munkamenet-követés és a HTTP cookiek). Az olyan rendszereket, amelyek a REST alapelveinek megfelelnek, az angol szakirodalom \emph{RESTful}-nak nevezi.

Egy RESTful alkalmazás a következő feltételek meglétét igényli:
\begin{itemize}
	\item a funcionalitás erőforrások formájában jelenik meg 
	\item minden erőforrás egyedileg megcímezhető, univerzális módon 
	\item minden erőforrás állapota egy egységes interfészen vihető át a kliens és az erőforrás között, ez az interfész jól definiált műveletekből és tartalomtípusokból áll 
	\item a protokoll kliens-szerver protokoll, mely emlékezetnélküli, cache-elhető és rétegzett.  
\end{itemize}

A hálózati komponensek (kliens és szerver) az erőforrások \linebreak \emph{reprezentációját} használják arra, hogy manipulálják az erőforrás által képviselt információt, ezt a reprezentációt cserélik ki egymás között egy interfészen. Konkrét példában: az interfész maga a HTTP, az erőforrás azonosítója az URI, reprezentációja pedig valamilyen XML dokumentum. A kommunikáció tetszőleges számú közvetítőn keresztül történhet, például proxy-kon, átjárókon, tűzfalakon keresztül. Az erőforrás-szemlélet lehetővé teszi azt, hogy az alkalmazásnak nem kell feltétlenül tudnia a közvetítő elemekről, elegendő az erőforrás azonosítóját és a szükséges műveletet ismernie.
 
A REST-et gyakran az RPC-vel (Remote Procedure Call -- távoli eljáráshívás) állítják szembe (Fielding ezt eredetileg nem tette). Míg a REST erőforrásokat használ, az RPC parancsokat. Az erőforrások főnevekkel írhatók le, a parancsok igékkel. Az erőforrásokon különböző, egyszerű műveletek végezhetők, de bonyolultabb funkciót már nehezebb megoldani. Az RPC-ben a módszerek összetettsége változó, bonyolultabb megoldásokat is lehet a parancsok mögé rejteni.

A következő példában az RPC-alapú alkalmazás a következő eljárásokat definiálja:

\begin{CoolVerbatim}
getUser()
addUser()
removeUser()
updateUser()
getLocation()
addLocation()
removeLocation()
updateLocation()
listUsers()
listLocations()
findLocation()
findUser()
\end{CoolVerbatim}
A kliens kódja pedig nagyjából a következőképp nézhet ki:
\begin{CoolVerbatim}
exampleAppObject = new ExampleApp('example.com:1234');
exampleAppObject.removeUser('001');
\end{CoolVerbatim} 
Hasonló funkcionalitású REST-alapú alkalmazásban erőforrásokat definiálunk:
\begin{CoolVerbatim}[commandchars=\\\{\}]
http://example.com/users/
http://example.com/users/\VerbParam{user}
http://example.com/findUserForm
http://example.com/locations/
http://example.com/locations/\VerbParam{location}
http://example.com/findLocationForm
\end{CoolVerbatim}
A fenti erőforrásokban a \emph{user} és a \emph{location} jelöli ki a különböző felhasználók és helyek egyedi azonosítóinak sorát, azaz minden felhasználónak és minden helynek egyedi erőforrása van! Ebben a példában az alkalmazás kódja így nézhet ki:
\begin{CoolVerbatim}
userResource = new Resource('http://example.com/users/001');
userResource.delete();
\end{CoolVerbatim}
Az elvégezhető műveleteket az interfész definiálja. Szokás szerint ezek általában a létrehozást, módosítást, törlést jelentik. A fenti példa az angol nyelvű Wikipédia REST szócikkéből származik.

\section{Az APP leírása}

Néhány bekezdéssel feljebb volt szó arról, hogy az APP a REST elveit követi, és hogy mennyire így van, azt már a dokumentáció első mondata is jól mutatja. Az RFC 5023 bevezetése így fogalmaz: Az Atom Publishing Protocol egy alkalmazás-szintű protokoll webes erőforrások publikálására és szerkesztésére HTTP és XML 1.0 segítségével. A hangsúly tehát itt is az erőforrásokon van, azok létrehozásán és manipulásásán (szerkesztés, törlés) túl pedig lehetőséget ad erőforrás-gyűjtemények kezelésére és felfedezésére. A protokoll nagy mozgásteret ad a szervereknek abban, hogy mit kezdhetnek a kliensek által küldött adatokkal, akár meg is változtathatják azokat, esetleg további műveleteket engedhetnek meg; a kliensszoftvereknek számolniuk kell azzal a lehetőséggel, hogy a szerver egy az RFC-ben meg sem említett státuszkóddal válaszol, vagy megváltoztatja a küldött adatot. A protokoll különös figyelmet szentel a cache-elhetőségnek.

Az erőforrások HTTP-n keresztül érhetőek el, URI-juk segítségével foghatóak meg. Az APP többféle erőforrást definiál, a legalapvetőbbek a be\-jegy\-zés-erő\-for\-rá\-sok és a média-erőforrások, közös nevükön a \emph{tagerőforrások}. A be\-jegy\-zés-erő\-for\-rá\-sok reprezentációja az Atom szindikációs formátumában megismert \emph{entry} dokumentum. A médiaerőforrások reprezentációja tetszőleges lehet (egy életszerű példában JPEG, PNG vagy más típusú kép- vagy videóállományról lehet szó). A tagerőforrások URI-jai kollekciókban jelenik meg, ezeket szintén erőforrásként lehet elérni, mely URI-val rendelkezik, reprezentációjuk Atom \emph{feed} típusú dokumentum. Ahhoz, hogy a média-erőforrások megjelenhessenek egy kollekcióban, tartozik hozzájuk egy úgynevezett médiacsatoló bejegyzés (media link entry), mely a bejegyzés-erőforrás egy formája. Így a média-erőforrásokhoz mindig tartozik bejegyzés-erőforrás is.

Az APP nem tesz különbséget az Atom feedek és a kollekciókhoz használt feedek között. Az, hogy a kollekció-erőforrások milyen URI-n találhatóak meg, egy \emph{service}-dokumentum írja le. Ez a dokumentum egy szolgáltatást munkaterületekre oszt, amelyekhez kollekciókat kapcsol, megadja azok URI-ját, típusát és a használható kategóriákat (a szindikációs formátum értelmében). A munkaterületek mibenlétét nem definiálja.

Az APP kizárólag a tagerőforrások kezeléséről rendelkezik. Minden művelet HTTP metódusokkal végezhető el. Erőforrás lekérdezése annak URI-jára küldött GET metódussal történik. POST metódus segítségével hozható létre egy új tagerőforrás, melyet a kollekció URI-ján kell végrehajtani. Ha a létrehozandó erőforrás típusa nem bejegyzés, akkor létrejön a médiaerőforrás, és hozzátartozó médiacsatoló bejegyzés is a kollekcióban. A erőforrások elnevezése dinamikus. Egy ismert tagerőforrás módosítása a PUT metódussal lehetséges, a törlésre pedig a DELETE metódus szolgál. A szerver a kérésekre adott válaszban a HTTP-ben meghatározott tetszőleges státuszkóddal válaszolhat, értelmezhet a specifikációban nem meghatározott metódust, és megváltoztathatja a küldött erőforrást, vagy akár megtagadhatja a kiszolgálását. Az ilyen esetek kezelésére a kliensnek kell felkészülnie. Két kérés között megváltozhat az erőforrás tartalma. Ha létrehozás vagy módosítás során megváltozik a küldött tartalom, a szerver célszerűen visszaküldheti a válasz törzsében a megváltozott tartalmat.

\subsection{Protokoll-dokumentumok}

A protokoll két új dokumentumtípust definiál: a kategórialista- és a service-dokumentumot. Természetesen mindkét dokumentumtípus szabályos XML állomány kell, hogy legyen. A fel nem ismert tageket és attribútumokat külső jelölésnek kell tekintenie a feldolgozónak, és nem jelezhet hibát. Az újonan bevezetett elemek egy új névtértben vannak, a \url{http://www.w3.org/2007/app} névtérben, amelyet rendszerint az \verb+app+ előtaggal jelölnek. Az új dokumentumok használják a szindikációs formátumban használt elemeket is, amelyek a \url{http://www.w3.org/2005/Atom} névtérben szerepelnek, általában \verb+atom+ prefixszel. Az itt és az ott használt definíciók megegyeznek.

A kategórialista egy gyűjteményben használható kategóriákat sorol fel. A dokumentum gyökere egy \verb+app:+\linebreak[0]\verb+categories+ elem, amelynek több \verb+atom:+\linebreak[0]\verb+category+ elemgyermeke lehet, vagy alternatívaként tartalmazhat egy \verb+href+ attribútumot, amely megadja annak a kategórialistának az URI-ját, amellyel ez a dokumentum azonos tartalmat képvisel. Ha vannak felsorolt kategóriák, a \verb+fixed+ attribútum jelöli azt, hogy a megadottakon kívül használható-e más kategória (\verb+yes+ vagy \verb+no+ tartalommal). Megadható egy séma-URI a \verb+scheme+ attribútummal, így azok a kategóriák, amelyeknél ez nem adott, ezt a sémát öröklik. Az \verb+atom:+\linebreak[0]\verb+category+ elemek definíciója megegyezik a szindikációs formátumban megadott definícióval.

A service-dokumentumok arra szolgálnak, hogy felsorolják az elérhető kollekciókat, ezzel biztosítsák a felderíthetőséget. A dokumentum gyökere egy \verb+app:+\linebreak[0]\verb+service+ elem, amelynek legalább egy \verb+app:+\linebreak[0]\verb+workspace+ gyermekelemmel rendelkeznie kell. Ezzel az elérhető munkaterületeket sorolja fel. A munkaterületek névvel és kollekciólistával rendelkeznek, ennek megfelelően az \verb+app:+\linebreak[0]\verb+workspace+ pontosan egy \verb+atom:+\linebreak[0]\verb+title+ és több \verb+app:+\linebreak[0]\verb+collection+ gyermekeleme lehet. Az \verb+app:+\linebreak[0]\verb+collection+ elem \verb+href+ attribútuma adja meg az adott kollekció URI-ját. Ezenkívül megadható a kollekció neve, az általa elfogadott dokumentumtípusok listája és a használható kategóriák listája, ezekre rendre az \verb+atom:+\linebreak[0]\verb+title+, \verb+app:+\linebreak[0]\verb+accept+ és \verb+app:+\linebreak[0]\verb+categories+ elemek szolgálnak, az elsőből pontosan egy, a másik kettőből tetszőleges számban lehet. Az \verb+app:+\linebreak[0]\verb+accept+ tartalma egy, az RFC 2616-ban meghatározott médiatípus lehet, ami gyakorlatilag egy MIME-típust jelent, hasonlóan a HTTP \verb+Accept+ fejlécéhez. Az \verb+app:+\linebreak[0]\verb+categories+ a korábban említettnek felel meg.

\subsection{Az APP kiterjesztései a szindikációs formátumhoz}

A protokoll számos helyen kiterjeszti a szindikációs formátumot, mivel azt a formátum megengedi. Ennek gyakran az az oka, hogy a protokoll a kollekciókat is feeddel írja le, sőt, a feedeket nem is különbözteti meg. A másik gyakori ok a formátum és a protokoll együttműködésének elősegítése.

\begin{itemize}
	\item Az \verb+app:+\linebreak[0]\verb+collection+ elem megjelenhet egy Atom dokumentumban is az \linebreak\verb+atom:+\linebreak[0]\verb+feed+ vagy az \verb+atom:+\linebreak[0]\verb+source+ elem gyermekeként, ahol a kollekciót határozza meg (amellyel szerkeszthető a feed).
	\item Lehetnek esetek, amikor nem célszerű megjeleníteni a teljes kollekciót. Erre az esetre a szerver egy részleges kollekciót küld a kliensnek. Ekkor a szerver a kollekció (ne feledjük, mint feed) további részeire linkeket helyezhet el. Ez az \verb+atom:+\linebreak[0]\verb+feed+ gyermekeként megadott \verb+atom:+\linebreak[0]\verb+link+ elemmel lehetséges, amelynek a \verb+rel+ attribútumában kell megadni, hogy az átadott URI milyen kapcsolatban van az aktuális részlettel; ennek értéke \verb+first+, \verb+previous+, \verb+next+ vagy \verb+last+ lehet, amely így az első, az előző, a következő vagy az utolsó részkollekciót jelöli.
	\item Az \verb+atom:+\linebreak[0]\verb+entry+ gyermeke lehet egy \verb+app:+\linebreak[0]\verb+edited+ elem, amely egy dátum konstrukció, a bejegyzés utolsó szerkesztési időpontját mutatja.
	\item A protokoll az \verb+atom:+\linebreak[0]\verb+entry+ elem alatti \verb+link+ elem \verb+rel+ attribútumában két új opciót vezet be. Ezek az \verb+edit+ és az \verb+edit-media+. Az ilyen link jelöli egy kollekciót reprezentáló feedben a tagerőforrás URI-ját, amelyen keresztül az erőforrás módosítható vagy törölhető. A bejegyzés-erőforráshoz tartozik az \verb+edit+ értékű link. Ha a kollekció médiát sorol fel, akkor az \verb+edit-media+ által mutatott URI tartozik a média-erőforráshoz, a másik annak médiacsatoló bejegyzéséhez (mint bejegyzés-erőforráshoz).
	\item Az \verb+atom:+\linebreak[0]\verb+entry+ elem alatt bevezetésre kerül az \verb+app:+\linebreak[0]\verb+control+. Ez tartalmaz egy további \verb+app:+\linebreak[0]\verb+draft+ elemet, amelynek értéke \verb+yes+ vagy \verb+no+ lehet. Ez jelöli azt, hogy a létrehozandó bejegyzés vázlat állapotban van, vagy már publikálható a külvilág felé.
\end{itemize}

\subsection{Az APP kiterjesztései és megjegyzései a HTTP-hez}

Az előírt funkcionalitás eléréséhez szükséges a HTTP kis mértékű kiterjesztése is. Ez főleg akkor válhat szükségessé, ha a protokolldokumentumok nem fejezik ki megfelelően az eredményt, vagy használatuk nem célszerű.

\begin{itemize}
	\item Nem a HTTP kiterjesztése, de szorosan összefügg azzal: az Atom dokumentumok érvényesek, akár feed, akár entry típusúak. Mindkét dokumentumtípust az \verb-application/atom+xml- MIME-típus jelöli, ez bizonyos esetekben nem elegendő. Ezért a protokoll megengedi ezután a \verb+type+ paraméter használatát, értéke \verb+entry+ vagy \verb+feed+ lehet. Így tehát egy entry típusú Atom dokumentum MIME-típusa: \verb-application/atom+xml; type=entry-.
	\item A bejegyzések elnevezése teljesen dinamikus, a szerver dönti el a nevet és az elérés URI-ját létrehozáskor. Azonban a kliens is javasolhat egy nevet, a POST metódus hívásakor a fejlécben átadható a \verb+Slug+ paraméter, ez a javasolt nevet jelöli. A szerver ezt megváltoztathatja, átalakíthatja, vagy akár figyelmen kívül is hagyhatja.
	\item Létrehozásnál a szerver válasza siker esetén \verb+201 Created+ lesz. A törzsben visszaküldött dokumentum azonban nem feltétlenül a teljes dokumentum, lehet annak egy része is. Az erőforrás URI-ját a fejléc \verb+Location+ része tartalmazza.
	\item Média-erőforrás létrehozásánál egyből két erőforrás is létrejön, egy a médiának, egy pedig a médiacsatoló bejegyzésnek. Ez a két különböző erőforrás a \verb+Location+ és a \verb+Content-Location+ fejlécekkel fejezhetők ki egyidőben.
	\item Az authentikáció tekintetében a protokoll nagyon rugalmas, és azt mondja, hogy bármilyen séma alkalmazható az illetéktelen hozzáférések ellen, de a minél nagyobb kompatibilitás érdekében egy Basic authentikáció implementálását javasolja TLS (Transport Layer Security - Transzport rétegbeli védelem) felett. Ha egy authentikációs kísérlet sikertelen, a szerver státuszkódja \verb+401 Unauthorized+ vagy \verb+403 Forbidden+ lehet.
	\item A szerver megtagadhatja például egy új bejegyzés felvételét akkor, ha az ahhoz megadott kategória nem szerepel a kollekció kategórialistájában, ame`nnyiben az rögített. Szintén megtagadhatja a szerver akkor, ha a kollekció nem támogatja az átadott típusú dokumentumot. (Például az \verb+app:+\linebreak[4]\verb+collection+-jei között nem található olyan \verb+accept+, amelyet a kliens át akar adni.)
	\item A kiszolgálónak és a kliensnek figyelmet kellene szentelnie a cache-el\-he\-tő\-ség\-re. Ez úgy érhető el, hogy amikor a szerver egy erőforrást ad vissza a reprezentációjában, a fejlécek között lehet egy \verb+ETag+, amely az erőforrás kivonatát jelentheti. A kliens ekkor lekérheti az erőforrást a kérés fejlécében az \verb+If-None-Match+ paraméterben a korábban ismert kivonattal, és ha az nem változott, a szerver a \verb+304 Not Modified+ státusszal válaszolhat. Ugyanígy, PUT metódussal történő módosítás esetén használható a \verb+If-Match+ fejléc, és ha a szerver ezt figyelembe veszi, lehetséges, hogy nem hajtja végre a módosítást, ha az erőforrás tartalma időközben megváltozott (szokásos státuszkód: \verb+412 Precondition Failed+).
\end{itemize}

\section{Példák}

A következőkben bemutatok néhány lehetséges módot, kérésekkel és a szerver válaszaival. A protokoll legáltalánosabb felhasználási módja a blogok írása; ehhez minden adott: a felhasznált képek, animációk és minden más egyszerűen kezelhetők média-erőforrásként, míg magukat a tényleges bejegyzéseket a be\-jegy\-zés-erőforrások reprezentálják. A blogbejegyzések ezután megjelenhetnek egy weboldalba ágyazva, egyedi URL-en olvashatók. \Acite{atomenabled}-ból származó példák következnek.

Mielőtt megkezdődhet a feedek kezelése, fel kell deríteni azokat. Ez a service-dokumentum URI-jára küldött GET kéréssel történhet. Az alábbi példában látható service-dokumentum két munkaterületet definiál. Az első munkaterület egy blogot határoz meg két kollekcióval, az egyik a bejegyzéseknek, a másik a bejegyzésekben használt képek számára. A bejegyzésekben használható kategóriákat egy külső kategórialista határozza meg, de attól el is lehet térni. A képek számára fenntartott kollekció a megadott típusú képeket fogadja el. A másik munkaterület egy mellékblogot ír le, az ebbe küldhető bejegyzések kategóriája kötött listából lehet.

\begin{CoolVerbatim}
<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://www.w3.org/2007/app"
         xmlns:atom="http://www.w3.org/2005/Atom">
  <workspace>
    <atom:title>Main Site</atom:title>
    <collection href="http://example.org/blog/main" >
      <atom:title>My Blog Entries</atom:title>
      <categories href="http://example.com/cats/forMain.cats" />
    </collection>
    <collection href="http://example.org/blog/pic">
      <atom:title>Pictures</atom:title>
      <accept>image/png</accept>
      <accept>image/jpeg</accept>
      <accept>image/gif</accept>
    </collection>
  </workspace>
  <workspace>
    <atom:title>Sidebar Blog</atom:title>
    <collection href="http://example.org/sidebar/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>
\end{CoolVerbatim}
Itt egy bejegyzés létrehozása látható. A példa mutatja azt is, hogy a létrehozáshoz a kliens Basic authentikációt használ. A Slug fejléc javasolja az új bejegyzés URI-ját.
\begin{CoolVerbatim}
POST /edit/ HTTP/1.1
Host: example.org
User-Agent: Thingio/1.0
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Type: application/atom+xml;type=entry
Content-Length: nnn
Slug: First Post

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Atom-Powered Robots Run Amok</title>
  <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
  <updated>2003-12-13T18:30:02Z</updated>
  <author><name>John Doe</name></author>
  <content>Some text.</content>
</entry>
\end{CoolVerbatim}
A szerver válaszában megtalálható az elem edit-URI-ja és kivonata (ETag). Ezenkívül a bejegyzés is megváltozik: kiegészül az edit-URI-val, amely a Slug figyelembevételével jön létre.
\begin{CoolVerbatim}
HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
Location: http://example.org/edit/first-post.atom
ETag: "e180ee84f0671b1"  

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Atom-Powered Robots Run Amok</title>
  <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
  <updated>2003-12-13T18:30:02Z</updated>
  <author><name>John Doe</name></author>
  <content>Some text.</content>
  <link rel="edit" href="http://example.org/edit/first-post.atom"/>
</entry>
\end{CoolVerbatim}

A feedelem lekérdezése \verb+If-None-Match+ fejléccel. A szerver válasza: \verb+304 Not+ \verb+Modified+.

\begin{CoolVerbatim}
GET /edit/first-post.atom HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
If-None-Match: "e180ee84f0671b1"
\end{CoolVerbatim}

A következő példa egy módosítási kísérlet, az If-Match fejléc használatával. Ha a szerver ezt figyelembe veszi és a kivonat egyezik, a válasza \verb+200 Ok+ lesz, ha a kivonat nem egyezik, \verb+412 Precondition Failed+ vagy \verb+409 Conflict+ lehet (a szerver implementációjától függően).

\begin{CoolVerbatim}
PUT /edit/first-post.atom HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Type: application/atom+xml;type=entry
Content-Length: nnn
If-Match: "e180ee84f0671b1"

<?xml version="1.0" ?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Atom-Powered Robots Run Amok</title>
  <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
  <updated>2007-02-24T16:34:06Z</updated>
  <author><name>Captain Lansing</name></author>
  <content>Update: it's a hoax!</content>
</entry>
\end{CoolVerbatim}
A bloghoz most hozzáadunk egy képet, ezt az eredeti bináris reprezentációjában tesszük.
\begin{CoolVerbatim}[commandchars=\\\{\}]
POST /edit/ HTTP/1.1
Host: media.example.org
Content-Type: image/png
Slug: The Beach
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: nnn

\VerbParam{bináris adat...}
\end{CoolVerbatim}
A kiszolgáló válasza már a képhez tartozó médiacsatoló bejegyzést tartalmazza. Ez gyakorlatilag a metaadatokat tárolja. Létrehozása után mind a média, mind a metaadat módosítható.
\begin{CoolVerbatim}
HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
Location: http://example.org/media/edit/the_beach.atom

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>The Beach</title>
  <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
  <updated>2005-10-07T17:17:08Z</updated>
  <author><name>Daffy</name></author>
  <summary type="text" />
  <content type="image/png" src="http://media.example.org/the_beach.png"/>
  <link rel="edit-media" href="http://media.example.org/edit/the_beach.png" />
  <link rel="edit" href="http://example.org/media/edit/the_beach.atom" />
</entry> 
\end{CoolVerbatim}
Ha minden szükséges képfile felkerült a szerverre, és tudjuk azok URL-jeit, elkészíthetjük a bejegyzést.
\begin{CoolVerbatim}
POST /blog/ HTTP/1.1
Host: example.org
Content-Type: application/atom+xml;type=entry 
Slug: A day at the beach 
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: nnn

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>A fun day at the beach</title>
  <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6b</id>
  <updated>2005-10-07T17:40:02Z</updated>
  <author><name>Daffy</name></author>
  <content type="xhtml">
      <xhtml:div xmlns:xhtml="http://www.w3.org/1999/xhtml">
          <xhtml:p>We had a good day at the beach.
              <xhtml:img alt="the beach"
                  src="http://media.example.org/the_beach.png"/>
          </xhtml:p>
          <xhtml:p>Later we walked down to the pier.
              <xhtml:img  alt="the pier"
                  src="http://media.example.org/the_pier.png"/>
          </xhtml:p>
      </xhtml:div>
  </content>
</entry> 
\end{CoolVerbatim}

\section{GData API}

A Google is kiterjedten használja az Atom publikációs protokollt szolgáltatásainak eléséhez \cite{gdataapi}. Atom-on keresztül lehet elérni a Gmail levelezésünket, a Calendar bejegyzéseit, vagy akár táblázatainkat a Docs szolgáltatásban; majd' mindegyik szolgáltatása elérhető feedeken keresztül, RSS, Atom vagy sok esetben JSON (JavaScript Object Notation) formátumban. Az RSS és az Atom kiterjesztési lehetőségeit erőteljesen kihasználja a szabvány adta lehetőségeken belül. Maga a GData protokoll feed létrehozására nem ad lehetőséget, de az egyes szolgáltatások ezt megtehetik. A GData az APP lehetőségein kívül különböző lekérdezéseket és optimista konkurrenciakezelést biztosít.

A lekérdezések biztosítása azt jelenti, hogy egy feedben lévő elemek szűrhetőek a feed lekérésekor GET-paraméterek segítségével. Alapesetben a teljes feed megjelenik lekérdezéskor. A \verb+q+ paraméter megadásával a feedelemeken teljesszöveges (full-text) keresést hajthatunk végre, vagyis csak azok az elemek jelennek meg a feedben, amelyekre a megadott szöveg illeszkedik. A \verb+category+ paraméter használható a kategóriák szerinti szűrésre, a paraméterben használható a \verb-|- (függőleges vonal) jel a \emph{vagy}, illetve a \verb-,- (vessző) az \emph{és} operátorok jelölésére. Az \verb+author+ paraméter teszi lehetővé az elemek szűrését azok szerzője szerint. Az \verb+updated-min+, \verb+updated-max+, \verb+published-min+, \verb+published-max+ értelemszerűen az elem frissítésére illetve létrejöttére fogalmaznak meg feltételt, értékük az RFC 3339 szerinti időbélyeg lehet. A lekérdezés kimenetét befolyásolja néhány további paraméter, ezek: \verb+start-index+ (1-től, az első megjelenítendő elem indexe), \verb+max-results+ (az elemek maximális száma), \verb+alt+ (alternatív reprezentáció, lehetséges értékei: \verb+atom+, \verb+rss+, \verb+json+, \verb+json-in-script+; alapértelmezett érték: \verb+atom+).

További két lehetőség van szűrésre. Egyrészt, a feed URL-jéhez a \Verb[commandchars=\\\{\}]-/\VerbParam{elemId}- hozzáfűzésével létrejött URL-en mindig az adott azonosítójú feedelemet lehet lekérdezni. Másrészt, a feed URL-jét kiegészítve a \Verb[commandchars=\\\{\}]+/-/\VerbParam{kategória1}\VerbDelim{[}/\VerbParam{kategória2}\VerbDelim{]...}+ sorozattal, a kapott URL-en a megadott kategóriák szerinti feedelemek fognak szerepelni.

A lekérdezésben kapott feedekben további elemek jelennek meg. A \verb+feed+ elem gyermekeként megtalálható lesz az \verb+openSearch:+\linebreak[0]\verb+totalResults+, \verb+openSearch:+\linebreak[4]\verb+startIndex+ és \verb+openSearch:+\linebreak[0]\verb+itemsPerPage+, ezek tartalma rendre a feedelemek teljes száma, az ebben a lekérdezésben megjelenő első feedelem indexe és az ebben a lekérdezésben megjelent feedelemek száma. Az oldalak közötti lapozást az APP szabályozásának megfelelően a \verb+feed+ elem alatt található azon \verb+link+ elemekkel lehet megoldani, amelyekben a \verb+rel+ attribútum értéke \verb+previous+ vagy \verb+next+.

Az optimista konkurrenciakezelés megvalósítása hihetetlenül egyszerű és véleményem szerint zseniális. Egy adott feedelem URL-je mindig a feed URL-jéhez konkatenált perjel, majd az entry azonosítója. Ennek a feedelemnek az edit-URI-ja az ehhez az URL-hez fűzött perjel, és a feedelem verziószáma, így, ha szerkesztjük, ez az URI azonnal érvénytelenné válik, a későbbi lekérdezésekben már az új edit-URI jelenik meg. Ez lehetetlenné teszi, hogy amíg egy kliens módosította egy feedelem tartalmát, a másik ezután azt felülírja vagy letörölje a korábbi verzió alapján.

\subsection{Authentikáció}

A legtöbb esetben a kliensalkalmazások egy bizonyos felhasználó nevében működnek. Ehhez a felhasználónak meg kell adnia nevét és jelszavát. A GData API többféle authentikációs módot is támogat. Az önálló asztali alkalmazások számára a ClientAuth módszert ajánlja; ha a kliens egy többfelhasználós webes alkalmazás, akkor célszerűbb az AuthSub vagy az OAuth módot választani. Az iGoogle- vagy OpenSocial-alapú alkalmazásokhoz is létezik módszer.

\subsubsection{AuthSub}

Ez a módszer a webes alkalmazásokhoz javasolt. A nagyobb biztonság érdekében az AuthSub interfész átveszi az alkalmazástól a felhasználó beléptetésének feladatát, azaz annak nem kell a felhasználó jelszavát kezelnie. A működése a következő: webalkalmazás (weboldal) átirányítja a felhasználót a \url{https://www.google.com/accounts/AuthSubRequest} oldalra, úgy, hogy közben annak átad egy GET-paramétert, a \verb+next+-et: ez tartalmazza annak az oldalnak az URL-jét, amelyre a felhasználó visszakerül a weboldalon. Az AuthSub rendszer bekéri a felhasználó adatait, s ha ez sikerül, a böngészőt visszairányítja a \verb+next+ paraméterben átadott oldalra, és annak egy \verb+token+ nevű GET-paraméterben visszaad egy tokent, amely a továbbiakban azonosításra használható. Ennek módja a következő: a kliens az authentikációt igénylő HTTP-kérés fejlécei között az \verb+Authorization+ fejlécen az \Verb[commandchars=\\\{\}]+AuthSub token="\VerbParam{korabbanKiadottToken}"+ értéket adja át. Ez egészen hasonló az AtomPub által javasolt megoldáshoz.

Ahhoz, hogy az adathoz végül valóban hozzáférjünk, a token kérésénél a \verb+scope+ paraméterben átadott értékkel kell jelezni, melyik Google-szolgáltatáshoz szeretnénk hozzáférni.

Az AuthSub további lehetőségei:
\begin{itemize}
  \item az alkalmazás egy regisztrációt követően használhat biztonságos bejelentkeztetést. Ha erre szükség van, a token kérésénél a \verb+secure+ paraméterben \verb+1+ értéket kell átadni
  \item ha az alkalmazás a felhasználó adatait nem egy lekérésre, hanem egy teljes munkamenetre (session) kéri, ezt a \verb+session+ paraméter \verb+1+ értékével kell jelezni
  \item használható a Google Apps szolgáltatásában regisztrált doménekben is, ehhez a \verb+hd+ paraméterben a kívánt domén nevét kell átadni
\end{itemize}

\subsubsection{OAuth}

Az OAuth egy széles körben elfogadott API az authentikációs eljárások terén. Sok tekintetben hasonlít az AuthSub módszerre abban az esetben, amikor azt regisztrációval és fokozott biztonsággal használjuk. Az OAuth használatához is regisztrálni kell az alkalmazást a Google-nél, majd egy biztonsági tanusítványt kell feltölteni, ez alapfeltétel ahhoz, hogy használni lehessen. Egy token kerül kiosztásra, három lépésben:
\begin{itemize}
  \item a webalkalmazás egy request-tokent igényel a \url{https://www.google.com/accounts/OAuthGetRequestToken} végponton, megadva GET- vagy POST-paraméterként az OAuth-hoz szükséges adatokat (verziószám, nonce, timestamp, \verb+consumer_key+, \verb+signature_method+) valamint a már ismertetett paramétert, amely behatárolja a használni kívánt adattárat. A válaszban megkapja a tokent és a hozzátartozó titkos kulcsot
  \item a webalkalmazás authorizálást kér az igényelt tokenre, a \url{http://www.google.com/accounts/OAuthAuthorizeToken} végponton, az \verb+oauth_callback+ paraméter tartalmazza azt az URL-t, amelyre sikeres azonosítás esetén átirányítja a böngészőt a Google oldala. Természetesen a tokent is meg kell adni a paraméterek között
  \item a webalkalmazás hozzáférési tokenre cseréli a request-tokent, a \url{https://www.google.com/accounts/OAuthGetAccessToken} URL-en POST metódussal, átadva a korábbi request-token adatait. A válasz tartalmazza az új hozzáférési tokent és a hozzátartozó titkos kulcsot
\end{itemize}

Mint látható, minden kérés HTTPS-en zajlik, ennek titkosításához a feltöltött tanusítványt kell használni. Ezután a kérést a megfelelő feed-en az \verb+Authorization+ fejléccel, \verb+OAuth+ sémában kell intézni a szerver felé, megadva az új tokent és a hozzá kapcsolódó adatokat.

\subsubsection{ClientLogin}

Ez a legegyszerűbb módja az authentikációnak a Google szolgáltatásaiban, ezt azonban az asztali alkalmazásokhoz ajánlja a Google. Ebben az esetben az alkalmazás maga gyűjti be vagy tárolja a felhasználó nevét (emailcím) és jelszavát, és a \url{https://www.google.com/accounts/ClientLogin} URL-re POST-kérést intéz, átadva paraméterként ezeket és az elérni kívánt szolgáltatás nevét. A HTTP-válasz tartalmazza a tokent, amelyet a szokásos módon, az \verb+Authorization+ fejléc megadásával, a \verb+GoogleLogin+ séma használatával lehet átadni a kívánt feed URL-jére küldött kérésben.

\subsection{Szolgáltatások}

A Google különböző szolgáltatásai nyilvánvalóan különböző jellegű adatokhoz adnak hozzáférést, különféle módokon. Sajnos itt nincs lehetőség arra, hogy teljes részletességgel bemutatásra kerüljenek a különböző típusú adatok elérésének módjai, ám a szolgáltatásokat néhány mondatban összefoglalom.

Minden szolgáltatásban közös az általuk használt szótár. Az adatelemek természetesen feedelemekként (\verb+<entry>+) jelennek meg, amelyben a rendszerint \verb+gd+ prefixszel jelölt \url{http://schemas.google.com/g/2005} névtérbe tartozó XML-elem\-ek írják le, adják meg az adott típusú (a Google terminológiájában: \emph{kind}) adatelem megfelelő értékeit. Ha egy feed egy adott típushoz tartozó adatelemeket kezel, akkor ezt az \verb+atom:+\linebreak[0]\verb+category+ XML-elemmel adja meg, ahol a kategória sémája (\verb+scheme+ attribútum) \url{http://schemas.google.com/g/2005#kind}, maga a kategória (\verb+term+ attribútum) pedig \url{http://schemas.google.com/g/2005#}\Verb[commandchars=\\\{\}]+\VerbParam{tipusNeve}+.

A Google által kezelt legfontosabb típusok külön is megadottak, ezek a Contact, Event illetve a Message típusok. Például a Contact típusban a feedelemben a kötelező XML-ele\-mek mellett megjelenik a \verb+gd:+\linebreak[0]\verb+email+, \verb+gd:+\linebreak[0]\verb+im+, \verb+gd:+\linebreak[0]\verb+phoneNumber+, amelyek rendre a kontakt emailcímét, azonnaliüzenetküldő-címét (instant messenger, IM) illetve telefonszámát írják le. A kapcsolat neve az \verb+atom:+\linebreak[0]\verb+title+ elem tartalma. Az Event típusban a \verb+gd:+\linebreak[0]\verb+when+, \verb+gd:+\linebreak[0]\verb+here+, \verb+gd:+\linebreak[0]\verb+who+ elemek játszanak fontosabb szerepet. A Message típus elemeiben a \verb+gd:+\linebreak[0]\verb+who+ elemek játszanak szerepet. Ez utóbbinál a feedelem kategóriája függ attól, hogy email, azonnali üzenet, kimenő üzenet vagy spam az adott üzenet közelebbi meghatározása, ennek megfelelően lehet \url{http://schemas.google.com/g/2005#message.inbox}, \url{#message.sent}, \linebreak \url{#message.chat}, illetve \url{#message.spam}. A \verb+gd:+\linebreak[0]\verb+who+ elem \verb+rel+ attribútuma határozza meg, hogy a tartalmában megadott személy a küldő, címzett, vagy például titkos másolat címzettje.

\subsubsection{Google Base}

Ez a szolgáltatás lehetővé teszi különböző cikkek, tételek leírását, amelyek pedig később kereshetővé válnak mások számára. Jelenleg csak az USA-ban és Németországban üzemel. A keresésre közzétehető cikkek között a legnépszerűbb fajták: események, hotelek, ingatlanok, munkalehetőségek, termékek, tanfolyamok, vizsgálati cikkek (review-k), receptek, járművek, bérlemények, és rengeteg további típusú adat tehető kereshetővé. Az adatelemekhez attribútumokat kapcsol a rendszer, amelyeket \verb+gd+ névterű XML-elemek írnak le.

\subsubsection{Blogger}

A Google által felvásárolt szolgáltatás. Mivel az APP gyakorlatilag a blogok kezeléséhez ideális, a GData alig tesz hozzá új elemeket, leszámítva a lekérdezéseknél tárgyalt dolgokat.

\subsubsection{Google Calendar}

A Google naptárszolgáltatása, amely egy felhasználónak több naptár kezelését és a naptárak felhasználók közötti megosztását is lehetővé teszi. Ebben az esetben létezik a naptáraknak egy feedje és a naptárakon belül az eseményeknek egy-egy feedje. A naptárspecifikus adatok leírására, például az időzóna, az esemény rejtett státusza, a naptárban megjelenő szín megadására a \url{http://schemas.google.com/gCal/2005} névtér ad lehetőséget, rendszerint \verb+gCal+ prefixszel jelölten.

\subsubsection{Google Code Search}

A nyílt forráskódú projektek lehetővé teszik forráskódjuk kereshetőségét, melyet a Google a Code Search szolgáltatásában használ ki. A keresés nem csak a webes felületen böngészőből indítható, feedet is biztosít hozzá az óriásvállalat. Ehhez mindössze egy GET-kérést kell intézni a \url{http://www.google.com/codesearch/feeds/search} URL-re a szokásos \verb+q+ paraméterrel, a válasz pedig feedben érkezik. A \url{http://schemas.google.com/codesearch/2006} névtér szokásos rövidítése \verb+gcs+, melyben a \verb+gcs:+\linebreak[0]\verb+file+ jelöli a file nevét, amelyben a találat van, a \verb+gcs:+\linebreak[0]\verb+match+ adja meg a találat szövegét és hogy ez hanyadik sorban van a file-ban, valamit \verb+gcs:+\linebreak[0]\verb+package+ egy URI-t biztosít a file-ra (verziókezelő szerver címe vagy egy tömörített állomány URL-je).

\subsubsection{Google Contacts}

Ez a Google-szolgáltatások által közösen elért adat, a felhasználó által ismert kapcsolatokat tárolja. A feedelemek típusa a korábban említett Contact.

\subsubsection{Google Book Search}

Hasonlóképp a Code Search-höz, a Book Search az elérhető könyvek tartalmában végez teljesszöveges keresést, és az eredményeket feed formájában bocsátja a felhasználó rendelkezésére.

\subsubsection{Google Documents List}

A Google Documents online, böngészőben szerkeszthető dokumentumokat tárol, ezekhez biztosít hozzáférést egy feeden keresztül. Ilyen módon a dokumentumok nem szerkeszthetők, ám a tartalmuk lecserélhető a médiaerőforráson keresztül (\verb+<link rel="edit-media" ... />+).

\subsubsection{Google Finance}

Ez a szolgáltatás egyrészt valósidejű (vagy késleltetett) tőzsdei adatokat biztosít, másrészt lehetővé teszi saját portfoliók nyilvántartását. A pénzügy-specifikus adatok leírását a \url{http://schemas.google.com/finance/2007} névtér elemei biztosítják.

\subsubsection{Google Health}

A Google Health azért jött létre, hogy tárolja és kezelje felhasználóinak egészségügyi adatait, információt, illetve betegségek, rendellenességek esetén segítséget nyújtson bizonyos hasznos információkkal. Feljegyzések vihetőek fel tünetekről, importálhatók korházi adatok és figyelemmel kísérhető egy egész kórtörténet; a rendszer a beavatkozások egymásrahatásáról is ad információkat. Valamint, beállíthatók gyógyszerek szedésének rendje. A Google feedjeiben a feedelemeket a Continuity of Care Record (CCS) szabvány XML-formátumából vett elemekkel egészíti ki.

\subsubsection{Google Notebook}

A Notebook szolgáltatás jegyzetek készítéséhez ad segítséget az interneten, valamint könyvjelzőket tárol. (Ennek a műnek egyes részei is ezen szolgáltatás segítségével készültek.) A szolgáltatásban egyaránt készíthetők magánjellegű és publikus jegyzetek. A GData API csupán a nyilvános jegyzetek feeden keresztüli olvasására ad lehetőséget. Ehhez két feed tartozik, egyik a felhasználó elérhető jegyzettömbjeit listázza, a másik pedig egy kiválasztott jegyzettömb jegyzeteit. A feedek nem igényelnek authentikációt és nem írhatóak, de a GData többi tulajdonsága, különösen a lekérdezhetőség érvényes marad.

\subsubsection{Picasa Web Albums}

A Picasa Web Albums lehetővé teszi fényképek elhelyezését, ezáltal azok ismerősökkel való megosztását. Publikus és privát albumok létrehozását, fényképek geotagelését (geográfiai adatokkal való felcímkézését), jegyzetek írását is támogatja. Ennek megfelelően a Picasa feedek igen sok külső szótár importálását igénylik. Az API lehetővé teszi az albumok teljeskörű kezelését feeden keresztül, minden adatával együtt (a különböző névterekben lévő elemek segítségével). Egy album \verb+self+ értékű rel-linkje egyben az adott album feedje is, amelyen keresztül az albumhoz tartozó képek kezelhetők.

Ez a feed tipikusan médiafeed, vagyis a kép eredeti bináris reprezentációjában kezelhető a GData API-val (mint az APP egy implementációjával). Érdekes megoldás azonban, hogy ez a feed együtt kezeli a médiacsatoló-bejegyzéseket és média-erőforrásokat. Az egyes feedelemek \verb+edit+ és \verb+edit-media+ értékű \verb+rel+ attribútummal rendelkező linkjei általában ugyanarra az URI-ra hivatkoznak. Ezen URI-n szerkeszthető a metaadathalmaz és a kép tartalma is, sőt, akár együtt is, a következőképp: a feed elfogadja a \verb+Content-Type:+ \verb+multipart/+\linebreak[0]\verb+related+ fejlécű feltöltéseket is, amelyben az egyik résztartalom MIME-típusa \verb-application/-\linebreak[0]\verb-atom+-\linebreak[0]\verb-xml-, a másiké pedig egy elfogadott képformátum típusa vagy egy videoformátum típusa (például \verb+image/+\linebreak[0]\verb+jpeg+ vagy \verb+video/+\linebreak[0]\verb+mpeg4+).

További feedek léteznek az egyes képekhez rendelt címkék felsorolásához, címkék hozzárendeléséhez, megjegyzések kezeléséhez, valamint az időbeli változások követéséhez.

\subsubsection{Google Spreadsheets}

A Google Spreadsheets korábban különálló szolgáltatásként működött, mostanra beolvadt a Google Documents-be, és egységes felületen használatos. Ám azok között egyedülálló módon lehetőséget ad a táblázatok kezelésére, feedeken keresztül. A szolgáltatás elsődleges feedje megadja a munkafüzetek listáját, illetve azok feedjeire mutató linkeket. Ezen feedeken kilistázhatók az adott munkafüzetek tartalma, munkalapok listájában. A munkalapok listájából kiválaszott egyik munkalap feedje kétféle módon ábrázolja a munkalapot: sorok listájában illetve cellák listájában. Ezeken keresztül a munkafüzetek, táblázatok teljes mértékben szerkeszthetők.

\subsubsection{Google Webmaster Tools}

A Webmaster Tools webmesterek számára kínál egy kiváló lehetőséget: megmutatja, hogyan látja a Google keresőmotorja ide beregisztrált oldalait. Ez azt jelenti, hogy diagnosztizálja tartalmát és jelenti, ha problémát talál, megmutatja, mik a leggyakoribb keresőszavak, amelyekre megtalálják az oldalt, hogy mikor volt utoljára frissítve a Google adattárházában, az oldalon található linkekről készít statisztikákat, és számos más adatot juttat a weboldal tulajdonosának tudomására. A feedek minden beállítást elérhetővé tesznek a GData API-n keresztül.

\subsubsection{YouTube}

A YouTube-ot talán senkinek nem kell bemutatni: ez a világ legnagyobb hálózati forgalmat generáló oldala -- egy videómegosztó oldal, amelyre percenként 13 órányi videóanyagot töltenek fel. Miután a Google felvásárolta a YouTube-ot, azonnal hozzálátott rendszerének beintegrálásába, így a Google felhasználói is saját azonosítójukkal használhatják az oldalt. A YouTube videók is elérhetők, kereshetők, szerkeszthetők Atom-feedeken keresztül. Ez az API hihetetlenül összetett, bonyolult rendszert vetít a külvilág felé.
