Revision as of 19:42, 23 February 2008

This should be considered preliminary documentation until Geeklog 1.5 is actually released. Details may change until then ...

Introduction

The Webservices API provides an interface for client software to talk directly to Geeklog and perform certain operations. Typical usage would be to use a desktop client to publish and edit stories without having to visit the website.

The Webservices in Geeklog 1.5 are based on the Atom Publishing Protocol. Other protocols could be implemented and added to be used in parallel (see Webservices API for technical details).

Setting things up

When configuring a client that supports the Atom Publishing Protocol (aka Atompub), you will usually be asked for a service document or an introspection URL. Both terms refer to the same thing, so the following will work for both:

On a standard Geeklog install at, say, www.example.com, the URL of the service document would be:

http://www.example.com/webservices/atom/?introspection

If your webserver is not set up to serve an index.php by default, you may have to use this URL instead:

http://www.example.com/webservices/atom/index.php?introspection

The service document provides all the information the Atompub client needs. You will only have to give your username and password as well (for your regular login to your Geeklog site).

Using only one plugin

If you want to use Atompub for only one plugin (where "plugin" also refers to the stories here), you can point your client to one of the following URLs for the service document instead:

http://www.example.com/webservices/atom/?introspection&plugin=story
http://www.example.com/webservices/atom/?introspection&plugin=staticpages

This way, the client will only see the service document for the given plugin.

Restricting access

Authentication Required

The Webservices can only be used by registered users. By default, any user with an active account can use the site's Webservices. Since we're currently only supporting access to stories and static pages, this will only be of limited use to users without Admin access (Story Admin or Static Pages Admin), though. They will only have read-only access to the stories and static pages that they can see on the site.

Authentication Problems

If your webserver is running PHP as a CGI, there may be a problem with the authentication not working. In this case, you will have to modify your .htaccess to forward the authentication headers.

Future Extensions

Future version of Geeklog may add access to the story submission queue. Also, third-party plugins may provide more useful access for normal users (e.g. the ability to edit their own forum posts).

Restrict Webservices Usage

To further restrict access to the Webservices, such that only certain users can use it, you can enable the Restrict Webservices? option in the Configuration. From that point on, only users with the specific webservices.atompub right can use the Webservices. There is also a pre-defined Webservices Users group that you can assign users to.

Clients

The list of Atompub clients is rather short at the moment since the protocol itself is still new (it was only approved in October 2007). However, many big names in the industry are already using Atompub for their services (e.g. Google for Blogger and the Google Calendar), so expect this list to grow soon.

Windows

• Windows Live Writer (Microsoft)
• Fude (Toru Marumoto)

Linux

• appfs (Peter Lacey) allows you to mount the contents of an Atompub-enabled site as a local filesystem.

Other

• Yulup is a Firefox extension.
• Atomic (Alex Milowski) is a Firefox extension.