[geeklog-devel] About the "internal" and Webservices APIs

[Dirk Haun]

Ramnath will be offline for a couple of days. In the meantime, I'm going
through the code he provided so far to see what's ready to go into CVS
and what's not there yet.

In case you don't know or remember, the task[1] from the Google Summer
of Code was asking for a Webservices API for Geeklog.

We decided to tackle this in a two-layer approach. There won't be many
Geeklog-specific clients for this API (initially or ever), so the API
needs to be able to make the best of what it gets. So when a client
sends something like "Hey, I've got a title and some text, and I think
this should become a story" then we won't usually get all the
permissions, comment, trackback, featured article, and other settings
that Geeklog has with that. So we need to accept as little as makes
sense and come up with reasonable defaults for the rest.

Since only, say, the static pages plugin can know what the defaults for
a new static page are, we need a way to tell it just that: Here's
something that should become a static page - please fill in the rest.

So we came up with what has come to be called the "internal API".
Effectively, it's a new plugin API function[2]

    PLG_invokeService($plugin, $verb, $input, $output, $svc_msg);

$verb would be 'submit' for storing something, 'get' to retrieve
something, etc.

The webservices API then sits on top of that API and translates whatever
protocol it's talking with the external client into calls of that function.

The nice thing is that PLG_invokeService can also be used by any other
add-on. To test this, I wrote a simple script (see attachment) that
imports *.txt files from Geeklog's data directory as new static pages.
Effectively, other than reading those files, all it does is

    $args = array(   
        'sp_id'      => $id,
        'sp_title'   => $title,
        'sp_content' => $content,
        'gl_svc'     => true
    );

    $plg_ret = PLG_invokeService('staticpages', 'submit', $args,
            $output, $svc_msg);

(where $id is the file's name, $title is the first line of text and
$content is the rest of the file)

Of course, if you have more information - permissions, whatever - that
you want to use for the new static page, you can simply add them in the
array. This is just to demonstrate the minimal example (actually, sp_id
is also optional - it will create a numeric ID if it's missing).

I can see this becoming VERY useful in writing import scripts and the
like, e.g. to help migration from (and to) other CMS.


For the actual webservices API, we settled on the Atom Publishing
Protocol (APP or Atompub, for short), which is in the final stages of
becoming an internet standard[3]. Clients are a bit rare (I have a
sidebar extension for Firefox that I haven't got to work yet), but are
beginning to look promising. For example, how about being able to mount
[4] your Geeklog site as a file system?

Of course, you could implement any other protocol on top of the internal
API. Atompub is just flexible, new, and - well - fun :-)


Okay, there's lots of work left to do. In CVS at this moment are the
changes to the static pages plugin to implement the internal API (so the
attached import script works with that). I also have Ramnath's changes
to the stories and the comments (although the latter are possibly not
quite working yet). And then there's the actual code for the webservices
API that I haven't even looked at yet. Expect at least some of this to
show up in CVS over the weekend.

Everything that should support the webservices API will have to be
rewritten to implement the internal API, of course. So that may be a bit
of work in places, but I think it's worth it. Not only for the
webservices API but also because the internal API makes so much more
possible. I have 3 or 4 half-finished add-ons here that are just waiting
for something like this ...

At this point, I'd also be interested to hear from other plugin authors
what they think about this. If the above sounded confusing, look at it
this way: You only have to implement the plugin's equivalents of
PLG_invokeService (which are several functions, one for each verb) and
your plugin will be able to talk to an Atompub client - or any other
client of any other protocol that somebody may come up with. How does
that sound?

Oh, and of course all the hard work was done by Ramnath. I only asked a
few stupid questions on occasion and made him start over when I didn't
like the outcome ;-)

bye, Dirk

P.S. And if you haven't noticed yet - we also have a new install script
in CVS, thanks to Matt West.


[1] <http://wiki.geeklog.net/wiki/index.php/SoC_webservices_publishing>
[2] <http://wiki.geeklog.net/wiki/index.php/
Webservices_API#Relation_of_the_Webse
rvices_component_with_the_rest_of_Geeklog>
[3] <http://www.ietf.org/internet-drafts/draft-ietf-atompub-protocol-17.txt>
[4] <http://wanderingbarque.com/appfs/using_appfs.html>


-- 
Geeklog Day at FrOSCon: August 25, 2007 - See you there!
http://www.geeklog.net/article.php/geeklog-day-at-froscon
-------------- next part --------------
A non-text attachment was scrubbed...
Name: spimport.php.gz
Type: application/x-gzip
Size: 1986 bytes
Desc: not available
URL: <https://pairlist8.pair.net/pipermail/geeklog-devel/attachments/20070810/7722a395/attachment.bin>