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

Fri Aug 10 21:40:51 EDT 2007

Dirk,

this all sounds very exciting, I have been wanting something like this 
for quite a while.
It reminds me of a feature request for stories I did once where I asked 
if we could not have templates saved for special purposes.

This sounds like another application of templates. Of course, one could 
save the HTML as a textfile somewhere, but a template would be better.
And of course, someone could go to the last story that looked the way it 
is supposed to look, but then you have to search which is annoying.
And all the permissions etc would not be saved.

1. stories: A lot of pages have recurring topics, articles about the 
same thing. If those articles looked similar, it would be easier if one 
could have the HTML of the article handy.
2. Calendar: Recurring events with a html structure that lists the even 
details
etc etc there is so much where this could help.

We would not even need another table for it, just a flag in the table 
which tells what is a template and exclude them from appearing online 
(like the draft-flag) and list them separately.
There could also then be a special template for the web-api.

Oliver

Dirk Haun wrote:
> 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-devel mailing list
> geeklog-devel at lists.geeklog.net
> http://eight.pairlist.net/mailman/listinfo/geeklog-devel
>   