The Web Services API, which is a part of glFusion's core code, provides an interface for client software to talk directly to glFusion and manage content utilizing the Atom Publication Protocol. Typical usage would be to use a separate web-based or desktop client to publish and edit stories without having to visit the website.
The Web Services in glFusion also syndicates content utilizing the Atom Syndication Format. Other protocols could be implemented and added to be used in parallel.
The Web Services API implements the Atom Syndication Format (RFC4287) and Atom Publication Protocol (RFC5023).
The Atom Syndication Format is similar to RSS 2.0, except that it allows the payload type to be 'labeled', (i.e. identified as to type or format). This allows you to syndicate all types of media, including audio, video, as well as escaped HTML/XHTML/XML, and even binary data.
The Atom Publishing Protocol essentially exposes an external interface to allow content to be managed remotely. It utilizes HTTP and XML as a methodology to access, edit and post content to the site.
Why Atom, you might ask? This blog post started the whole thing. General information about the Atom Syndication and Publication Protocols can be found here.
A lot of really specific and technical information can be found at atomenabled.org. Note that glFusion's core implementation only works with PHP v5 or greater.
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 glFusion install at, say, www.example.com, the URL of the service document would be:
http://www.example.com/webservices/atom/?introspection
If your web server 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 glFusion site).
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.
The Web Services API can only be used by registered users. By default, any user with an active account can use the site's Web Services. 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.
If your web server 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.
To further restrict access to the Web Services, 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 Web services. There is also a pre-defined Web Services Users group that you can assign users to.
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 (i.e. Google for Blogger and the Google Calendar), so expect this list to grow soon.