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)

GL Directives

The $input array should contain all the information required for the successful processing of the requested action. Some keys in this array are, however, reserved for providing useful processing information to the plugin. These array keys MUST NOT be used to store user-provided information.

'gl_svc'	If true, this indicates that the function has been invoked by the webservices component. Ideally, this should not matter, but for existing plugins, it eases the transition to an Atom-enabled server by allowing the plugin to differentiate between a webservice call and an invocation by the HTML component.
'gl_edit'	If true, this indicates that the 'submit' verb has been invoked in 'Edit' mode, which means an existing item is to be modified. On successful completion, the Atom client will receive a 'HTTP/1.1 200 Ok' response, rather than a 'HTTP/1.1 201 Created' response that is normally transmitted for new items.
'gl_etag'	If set, this variable contains the If-Match HTTP header (with the double-quotes stripped) sent by the client along with a updation request. Unless it is empty, this variable MUST be compared to the 'updated' property of the existing item before the item is modified. This ensures that the item has not been modified in the interval between its retrieval by the client and subsequent updation.

Standard Input Keys

Apart from the GL directives, there are some more array keys for the $input variable that have standard meanings. These include -

'id'	The ID of the item that the client wants to refer to.
'title'	The title of the item under consideration.
'author_name'	The name of the author, as provided by the client.
'category'	An array of all the categories for the item, supplied by the user. (See: Categories)
'updated'	The date and time, as accurate as possible when the item was last updated. Since the 'updated' value is used to determine if the item has been modified, it is STRONGLY RECOMMENDED that the value be updated on each modification of the item. This value is in the RFC 2822 format. The following keys are also updated with the local time, based on the value of $input['updated'] - 'publish_month' 'publish_year' 'publish_day' 'publish_hour' 'publish_minute' 'publish_second'
'summary'	A summary of the content of the item.
'content'	The main content of the item.

Output Array

The $output variable contains all the output generated by the plugin function. In error conditions, the $output variable MAY be a string rather than an array, since the webservice does not handle the $output variable under error conditions. However, this is NOT RECOMMENDED.

The items listed in Section Standard Input Keys MUST be filled in appropriately by the plugin function before returning.

Service Messages

The $svc_msg array is used to return specific messages to the webservice component. The following array keys are understood -

'id'	The ID of the item under consideration. For POST requests, this ID forms a part of the URI returned in the Location header, as specified by the Atom protocol. For GET requests, this ID forms part of the URI that is inserted into each entry.
'error_desc'	When the plugin function returns an error code, the webservice looks at this value and returns it to the user if it is non-empty. This is particularly useful for making the 400 Bad Request errors more descriptive and plugin-specific.
'gl_feed'	The plugin should set this variable to true if the plugin is returning multiple items, rather than a single item. This means that $output is expected to be an array of arrays.
'offset'	This variable indicates the number of items (from the start) that the server would have to skip in order to present the next partial list of items of the collection. This value forms a part of the URI inserted into the Atom feed document.
'output_fields'	This array provides the list of keys of the $output variable that should be converted into XML and displayed to the user. This is primarily used because the plugin function may want to hide some of the output values in case of the webservice. This list MUST NOT include any of the standard Atom elements (See: Standard Input Keys). Those elements will be displayed to the user, even without being listed here.