Revision as of 20:57, 6 January 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).

Restricting access

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.

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).

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.