View source for Using the Webservices

''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:

<pre>http://www.example.com/webservices/atom/?introspection</pre>

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

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

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:

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

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 [[Webservices_API#Authentication|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 <tt>webservices.atompub</tt> right can use the Webservices. There is also a pre-defined <tt>Webservices Users</tt> 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 ==

* [http://writer.live.com/ Windows Live Writer] (Microsoft)
* [http://www.witha.jp/eXeries/software/ Fude] (Toru Marumoto) 

== Linux ==

* [http://wanderingbarque.com/appfs/using_appfs.html appfs] (Peter Lacey) allows you to mount the contents of an Atompub-enabled site as a local filesystem.

== Other ==

* [http://www.yulup.org/ Yulup] is a Firefox extension.
* [https://addons.mozilla.org/firefox/3188/ Atomic] (Alex Milowski) is a Firefox extension.