Webservices API

Webservices Documentation for Geeklog 1.4

The purpose of the Geeklog webservices module is to provide an application layer interface for Geeklog that can be used by standardized clients such as aggregators, desktop publishing software etc. to interact with the web-server, and create and update content programmatically.

The Atom Publishing Protocol is the protocol that has been implemented for this purpose. At the time of this writing, the protocol is in the latest stages of becoming an official internet standard.

Relation of the Webservices component with the rest of Geeklog

In order to incorporate the webservice, the Geeklog code has been re-organized. The purely functional code has been shifted into 'service' methods, separating it from the code that manages the display and rendering of the plugin. For instance, there are now functions called 'service_post_story' and 'service_delete_story' that take an array of parameters as argument and perform the 'post' and 'delete' functions respectively. These methods can be called by the webservice and the HTML scripts alike. When called from any external functions, these functions must be called by using the PLG_invokeService method, like this:

PLG_invokeService($plugin, $verb, $input, $output, $svc_msg);

$plugin	The plugin whose function needs to be invoked
$verb	The action to be performed ('post,' 'delete,' etc.)
$input	An array of input parameters Some of these input parameters may be optional, depending on the plugin. The plugin MUST ignore unknown parameters.
$output	An array of output parameters passed by reference. The calling function may choose to display these parameters as it chooses. In the story and staticpages implementation, this variable is a string in a few cases, but it is STRONGLY RECOMMENDED that this variable be treated as a simple array of parameter-value pairs. On successful operation, the webservice script MAY display the content of this variable to the client in the form of XML.
$svc_msg	This array, short for "service messages" is used exclusively by the webservice to get certain types of control information from the plugin.

The above invocation calls the function (provided it exists)

service_<verb>_<plugin>(<input>, <output>, <svc_msg>)

where <output> and <svc_msg> are passed by reference to the plugin.

The <output> and <svc_msg> arrays MUST be filled in by the plugin function, so that it can be acted upon by the calling function.

Implications for writing a plugin

If a plugin is developed according to certain rules, it can automatically provide an Atom-enabled interface for the client. For this, the following verbs must be implemented:

submit	This verb handles any kind of data posted to the server. In the context of the Atom protocol, this verb is used to create new items or update existing items on the server. (See: GL Directives) Successful completion results in the return of either a 'HTTP/1.1 201 Created' response or a 'HTTP/1.1 200 Ok' response to the Atom client.
delete	This verb deletes a specified resource on the server.
get	This verb handles the retrieval of information existing on the server. When accessed via the webservice, each item is serialized into XML, in the Atom Syndication format (See: RFC 4287). The plugin may return a single entry or multiple entries. The plugin MUST return a single item if the $id variable is set. (See: Service Messages)

The Atom specifications have been extended to allow verbs other than the ones above. (See: Atom extensions)