<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<sect2 id="blogatomapi"><title>Atom API</title>

<para>The Atom API is a protocol for publishing and editing a blog entries using 
the common HTTP verbs:</para>

<simplelist>
  <member>GET - used to retrieve a blog post or perform query</member>
  <member>PUT - used to update an existing blog post</member>
  <member>POST - used to create a new post or perform an update action</member>
  <member>DELETE - used to remove a post</member>
</simplelist>

<formalpara>
  <title>Authentication</title>
  <para>The Atom API implementation accepts both HTTP basic and digest
authentication.  All requests for post content modification require an
authorization. Furthermore, the account used for authentication is checked to be 
the blog owner or have granted privileges on that particular blog.
The retrieval operations; which no post modification is possible are not
required to ask for authentication.</para></formalpara>

<formalpara>
  <title>Introspection</title>

<para>When editing the content of a blog, the first thing is to find out the servers capabilities. 
So the 'introspection' file lists all the functions that a given site supports.</para></formalpara>

<example id="ex_blogatomintrospection"><title>Intropsection</title>

<para>Request:</para>

<programlisting><![CDATA[
GET /Atom/Http/intro?b=128 HTTP/1.1
Host: example.com
]]></programlisting>

<para>Response:</para>

<programlisting><![CDATA[
HTTP/1.1 200 OK
Server: Virtuoso
Connection: Keep-Alive
Date: Mon, 10 Nov 2003 10:21:55 GMT
Content-Type: text/xml; charset="ISO-8859-1"
Content-Length: 417

<?xml version="1.0" encoding="ISO-8859-1"?>
<introspection xmlns="http://example.com/newformat#" >
  <create-entry>http://example.com/Atom/Http/entry?b=128</create-entry>
  <user-prefs>http://example.com/Atom/Http/prefs?b=128</user-prefs>
  <search-entries>http://example.com/Atom/Http/search?b=128</search-entries>
  <categories>http://example.com/Atom/Http/categories?b=128</categories>
</introspection>
]]></programlisting>
</example>

<formalpara><title>Posting a new entry</title>

<para>To post a new entry, the HTTP POST must be performed with
MIME type '<computeroutput>application/x.atom+xml</computeroutput>' 
for the request content. If server accepts the request a 
<computeroutput>Location:</computeroutput> HTTP header will be 
returned to the client containing the URL to the newly created post.</para>
</formalpara>

<example id="ex_blogatompost"><title>Posting an Entry</title>

<programlisting><![CDATA[
POST /Atom/Http/entry?b=128 HTTP/1.1
Content-Type: application/x.atom+xml
Content-Length: nnn
Authorization: ...

<?xml version="1.0" encoding="iso-8859-1"?>
<entry xmlns="http://example.com/newformat#">
  <title>My Entry</title>
  <author>
    <name>Blog Author</name>
  </author>
  <issued>2003-11-04T17:29:29</issued>
  <content type="application/xhtml+xml" xml:lang="en-us">
    <p xmlns="">Hello world!</p>
  </content>
</entry>
]]></programlisting>

<para>The response from server would be:</para>

<programlisting><![CDATA[
HTTP/1.1 201 Created
Location: http://host:port/Atom/Http/entry?b=128&id=nn
]]></programlisting>
</example>

<formalpara><title>Editing an Existing Entry</title>

<para>An entry can be edited via the HTTP PUT method.
The URL used for PUT must be one returned by the 
<computeroutput>Location:</computeroutput> header of the 
POST response or those returned from entry-search. 
The content of PUT request is same as for posting a new entry.
</para></formalpara>

<example id="ex_blogatomedit"><title>Editing a weblog entry</title>

<programlisting><![CDATA[
POST /Atom/Http/entry?b=128&id=nn HTTP/1.1
Content-Type: application/x.atom+xml
Content-Length: nnn
Authorization: ...

<?xml version="1.0" encoding="iso-8859-1"?>
<entry xmlns="http://example.com/newformat#">
  <title>My Entry</title>
  <author>
    <name>Blog Author</name>
  </author>
  <issued>2003-11-04T17:29:29</issued>
  <content type="application/xhtml+xml" xml:lang="en-us">
    <p xmlns="">Hello world! (edit test)</p>
  </content>
</entry>
]]></programlisting>

<para>The server response is:</para>

<programlisting><![CDATA[
HTTP/1.1 205 Reset Content
]]></programlisting>
</example>

<formalpara><title>Retrieving an Entry</title>

<para>Retrieval of an existing entry is the simple, usual HTTP GET 
request with URL to the entry.</para></formalpara>

<example id="ex_blogatmgetentry"><title>Retrieving an Entry</title>

<programlisting><![CDATA[
GET /Atom/Http/entry?b=128&id=nn HTTP/1.1
Accept: application/x.atom+xml
]]></programlisting>

<para>Server will respond with </para>

<programlisting><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/x.atom+xml
Content-Length: nnn

<?xml version="1.0" encoding="iso-8859-1"?>
<entry xmlns="http://example.com/newformat#">
  <title>My Entry</title>
  <author>
    <name>Blog Author</name>
  </author>
  <issued>2003-11-04T17:29:29</issued>
  <content type="application/xhtml+xml" xml:lang="en-us">
    <p xmlns="">Hello world! (edit test)</p>
  </content>
</entry>
]]></programlisting>
</example>

<formalpara><title>Deleting an Entry</title>

<para>To remove permanently an existing entry an HTTP DELETE
method is used with URL to the entry.</para></formalpara>

<example id="ex_blogatomdelete"><title>Deleting an Entry</title>

<programlisting><![CDATA[
DELETE /Atom/Http/entry?b=128&id=nn HTTP/1.1
]]></programlisting>

<para>Response:</para>

<programlisting><![CDATA[
HTTP/1.1 200 OK
]]></programlisting>
</example>

<formalpara><title>Searching Entries</title>

<para>To retrieve a subset of messages based some criteria a search 
should be performed.  The current implementation supports two variants: 
range and last_N.</para></formalpara>

<example id="ex_blogatomsearch"><title>Searching</title>

<programlisting><![CDATA[
GET /Atom/Http/search?b=128?last=7 HTTP/1.1
Accept: application/x.atom+xml
Host: example.com
Authorization: ...
]]></programlisting>

<para>or </para>

<programlisting><![CDATA[
GET /Atom/Http/search?b=128&start-range=2&end-range=27 HTTP/1.1
Accept: application/x.atom+xml
Host: example.com
Authorization: ...
]]></programlisting>

<para>Response from server will look like:</para>

<programlisting><![CDATA[
<search-results xmlns="http://example.com/newformat#">
<match title="Classic ASP Framework. Make your Classic...">http://example.com/Atom/Http?b=128&amp;id=6</match>
<match title="DB Navigator - an open source .NET control">http://example.com/Atom/Http?b=128&amp;id=4</match>
<match title="Sort an Array with Non-Comparable Items">http://example.com/Atom/Http?b=128&amp;id=5</match>
<match title="SignedXML Licensing Sample">http://example.com/Atom/Http?b=128&amp;id=7</match>
<match title="TicTacToe">http://example.com/Atom/Http?b=128&amp;id=1</match>
<match title="Check your eMails in Hotmail using HTTPMail">http://example.com/Atom/Http?b=128&amp;id=2</match>
<match title="Slashdot.org RSS Feed Reader">http://example.com/Atom/Http?b=128&amp;id=3</match>
</search-results>
]]></programlisting>

<para>Each sub element of the search result contains the title of the post and its 
URL.  These URLs can be used retrieved using the GET method, or modified via PUT/DELETE
methods.</para>
</example>

<sect3 id="blogatomclientapi"><title>Atom Client API</title>

<para>The Atom Client API is a mirror of the blogger API functionality, 
but uses the Atom protocol instead of XML-RPC.  Before the Atom API can 
be put to use, the introspection file must be retrieved in order to know 
the URLs for the requests.</para>

<itemizedlist>
<listitem>
<para><function>atom.new_Post 
  <paramdef>in <parameter>uri</parameter> varchar</paramdef>
  <paramdef>in <parameter>req</parameter> "blogRequest"</paramdef></function></para>

<para>This is to post a new entry to the blog identified by 'uri'.
The 'req' must be initialized with authentication and entry data. 
This function returns the URL to the new entry. This could be used with sequential
GET/PUT or DELETE requests for it. </para>
</listitem>

<listitem>
<para><function>atom.edit_Post 
  <paramdef>in <parameter>uri</parameter> varchar</paramdef>
  <paramdef>in <parameter>req</parameter> "blogRequest"</paramdef></function></para>

<para>This is to modify an existing entry identified by 'uri'.
The 'req' must be initialized with authentication and entry data.
The function returns true on success or will signal an error.</para>
</listitem>

<listitem>
<para><function>atom.delete_Post 
  <paramdef>in <parameter>uri</parameter> varchar</paramdef>
  <paramdef>in <parameter>req</parameter> "blogRequest"</paramdef></function></para>

<para>This is to delete an existing entry identified by 'uri'.
The 'req' must be initialized with authentication data.
The function returns true on success or will signal an error.</para>
</listitem>

<listitem>
<para><function>atom.get_Post 
  <paramdef>in <parameter>uri</parameter> varchar</paramdef>
  <paramdef>in <parameter>req</parameter> "blogRequest"</paramdef></function></para>

<para>This is to retrieve an existing post entry identified by 'uri'.
The 'req' must be initialized with authentication data.
This function will return on success an MTWeblogPost UDT, filled with 
post entry data.</para>
</listitem>

<listitem>
<para><function>atom.get_RecentPosts 
  <paramdef>in <parameter>uri</parameter> varchar</paramdef>
  <paramdef>in <parameter>req</parameter> "blogRequest"</paramdef>
  <paramdef>in <parameter>num</parameter> int</paramdef></function></para>

<para>This is to retrieve last-N post entries identified by blog search URL - 'uri'.
The 'req' must be initialized with authentication data.
'num' is number of entries to return.</para>

<para>This function returns an array of arrays containing the title and URL of the 
matching blog posts.</para>
</listitem>

<listitem>
<para><function>atom.get_Intro 
  <paramdef>in <parameter>uri</parameter> varchar</paramdef></function></para>

<para>This is used to return Introspection information for a blog identified by 
introspection file - 'uri'.</para>
</listitem>
</itemizedlist>


<example id="ex_blogatomclientapi"><title>Using the Atom Client API</title>

<para>Getting the introspection info about a blog</para>

<programlisting><![CDATA[
declare x any;
x := atom.get_Intro ('http://example.com/Atom/Http/intro?b=128');
-- x will contain
-- (("create-entry" "http://example.com/Atom/Http/entry?b=128" )
--  ("user-prefs"
-- "http://example.com/Atom/Http/prefs?b=128" ) ("search-entries"
-- "http://example.com/Atom/Http/search?b=128" ) ("categories"
-- "http://example.com/Atom/Http/categories?b=128" ) )
]]></programlisting>

<para>make a new entry</para>

<programlisting><![CDATA[
declare resp any;
declare req "blogRequest";
declare stru "MTWeblogPost";

req := new "blogRequest" ('', '', '', 'dav', 'dav');
stru := new "MTWeblogPost" ();
stru.title := 'My title'
stru.description := '<p>hello</p>';
req.struct := stru;
resp := atom.new_Post ('http://example.com/Atom/Http/entry?b=128', req);
]]></programlisting>

<para>The response, resp, would contain: 
  <computeroutput><![CDATA[http://example.com/Atom/Http/entry?b=128&id=1]]></computeroutput></para>

<para>edit an entry:</para>

<programlisting><![CDATA[
declare resp any;
declare req "blogRequest";
declare stru "MTWeblogPost";

req := new "blogRequest" ('', '', '', 'dav', 'dav');
stru := new "MTWeblogPost" ();
stru.title := 'test'
stru.description := '<p>hello from me</p>';
req.struct := stru;
atom.edit_Post ('http://example.com/Atom/Http/entry?b=128&id=1', req);
]]></programlisting>

<para>delete it:</para>

<programlisting><![CDATA[
atom.delete_Post ('http://example.com/Atom/Http/entry?b=128&id=1', req);
]]></programlisting>
</example>

<tip><title>See Also:</title>
  <para><ulink url="https://tools.ietf.org/html/rfc5023">RFC 5023: The Atom Publishing Protocol</ulink></para></tip>
  </sect3>
</sect2>