Latest revision as of 12:58, 8 May 2009

Webservices Documentation for Geeklog 1.5

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. The protocol is now an official internet standard (RFC 5023).

For an end-user documentation, please see Using the Webservices.

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

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:

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

Enabling webservices for a plugin

In order to enable webservices for a plugin, it must implement the plugin_wsEnabled_<plugin> function AND this function must return true. For example:

function plugin_wsEnabled_staticpages()
{
    return true;
}

For a plugin that supports webservices, webservices can be disabled by returning false in the function above.

The following function can be used in the rest of the GL code to check if a specific plugin supports webservices:

PLG_wsEnabled($type);

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.

Standard Input Keys

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

       'publish_month'
       'publish_year'
       'publish_day'
       'publish_hour'
       'publish_minute'
       'publish_second'

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 -

HTTP Responses and Return Codes

The service_<verb>_<plugin> functions MUST return one of the following codes

The Atom server returns one of the following responses on successful (code>PLG_RET_OK</code>) or unsuccessful (all other return codes) completion of an operation:

Atom Client Requirements

A standard Atom client can be used to post, edit, delete and get items to the server using any plugin. A Geeklog specific client would provide fine-grained control over the input data. (See: Atom Extensions)

XML Namespaces

The namespaces that are expected by the webservice are

• http://www.w3.org/2007/app - Atom publishing protocol
• http://www.w3.org/2005/Atom - standard Atom elements
• http://www.geeklog.net/xmlns/app/gl - Geeklog-specific elements

Atom Extensions

The webservice ignores all XML elements that do not belong to one of the above namespaces. Some elements belonging to the http://www.w3.org/2005/Atom are interpreted as explained in Section: Standard Input Keys. All other elements belonging to either the http://www.w3.org/2005/Atom or http://www.geeklog.net/xmlns/app/gl namespaces are transformed thus:

$input[<name>] = <value>

where

• <name> is the local name of the node
• <value> is the value of the node's content (if the content is text-only) OR the text-values contained in all the child nodes, stored as an array

For example

<somename>John</somename>                   becomes $input['somename'] = 'John';
<somename><param>abcd</param></somename>    becomes $input['somename'] = array ( 'abcd' );

To invoke a verb other than 'submit,' 'delete' or 'get,' the client should insert the following XML snippet as a child of the atom:entry node

<action xmlns="http://www.geeklog.net/xmlns/app/gl">$verb</action>

where $verb is the requested verb. The content should be submitted as a POST request. Successful operation returns a '201 Created' HTTP response.

Categories

Atom categories correspond to Topics in Geeklog. The Atom server has support for multiple categories. atom:category elements of the form -

<category xmlns="http://www.geeklog.net/xmlns/app/gl" term="sometopic"/>
<category xmlns="http://www.geeklog.net/xmlns/app/gl" term="someothertopic"/>

are converted into -

$input['category'] = array ( 'sometopic', 'someothertopic' );

If the plugin can support only one topic, then it MAY reject all or all except one category provided by the user.

The server provides the client a list of possible categories using the 'getTopicList' verb.

URI Details

The webservice follows the standard Atom discovery mechanism to let clients know the URIs of the available services. A webservice URI is of the form -

http://<domain>/webservices/atom/?plugin=<plugin_name>
http://<domain>/webservices/atom/?plugin=<plugin_name>&id=<object_id>
http://<domain>/webservices/atom/?plugin=<plugin_name>&offset=<offset_value>

In the absence of the <object_id> parameter value, the URI is assumed to point to the entire collection. In this case, the first <offset_value> items MAY be skipped on a GET request. If the plugin provides support for skipping elements, then the $svc_msg['offset'] value, on return, MUST contain the offset value for obtaining the next set of items in the collection.

If the <object_id> value is invalid but not empty, the plugin function must return an error response.

Authentication

The webservice uses the Basic authentication scheme(1). If the client receives a '401 Unauthorized' HTTP response, then it MAY send another request with suitable credentials. The authentication string passed by the client is expected to be -

base64 ( <username>:<password> )

Basic authentication is handled implicitly by the webserver in most cases.

If PHP is installed as a CGI binary on your server, then authentication might fail because Apache may not pass on the authorization headers to PHP. In that case, update your .htaccess file to include the following lines:

RewriteEngine on
RewriteRule .* - [E=REMOTE_USER:%{HTTP:Authorization},L]
RewriteCond %{HTTP:Authorization} username=\"([^\"]+)\"

(1) A functional implementation of WSSE authentication is included in system/lib-webservices.php but can not be used since Geeklog does not have access to the user's unencrypted password and therefore can't perform the authentication ...

Implementation Details

Length of Entry IDs

Atompub clients will usually include an ID when creating a new entry. To ensure that this ID is unique and can be used, Geeklog will need to know the max. length of an ID as used by a plugin. For stories and static pages, that max. length is 40 characters and has now been hard-coded as constants.

Earlier versions of Geeklog did not use a hard-coded length, so it was easy to use longer IDs (e.g. for SEO purposes) by simply changing the database and the input fields in the story or static pages editor. If you did that, you will have to adjust the constants accordingly or you will not be able to modify your entries through the webservices API.

Slug

Some Atompub clients will send a Slug: header with the POST request when creating a new entry. This header contains a text string that the client suggests to be used in the ID for the new entry.

Geeklog will try to make use of the Slug: header, if it decides that it needs to create a new ID for the entry. However, the content will be ignored if it contains %-encoded characters since those are usually non-printable or Unicode characters that can not be used in an entry ID in Geeklog.

The content of the Slug: header is also available as a 'slug' entry in the input array. Plugins can either use it directly or pass it to the WS_makeId function to create a new ID.

Security Implications

Plugin developers should be aware that writing a function of the form -

service_<x>_<y> (...)

makes the function open to the public, in the sense that it can be called using the webservice, with appropriate parameters. Functions should not be named in this way, unless they are intended to be called independently.

An important corollary is that function calls of the type -

if (<security_check>) {
    PLG_invokeService(...);
}

are BAD, because the same function can be called from the webservice WITHOUT the <security_check>.

Compliance

To the best of our knowledge, the webservices / Atompub implementation in Geeklog complies with RFC 5023 (and RFC 4287, where applicable).

Atom Protocol Exerciser

The Atom Protocol Exerciser (aka The APE) by Tim Bray performs several operations against an Atompub service (such as the one implemented in Geeklog) and evaluates the responses, i.e. it is looking for expected results according to the RFCs.

At the time of this writing (January 2008) Geeklog's Atompub implementation for the Static Pages plugin passes all of the APE's tests.

Non-conformance of Stories Implementation

The Atompub implementation for stories fails one test - but that was a deliberate decision. In this test, the APE creates 3 stories, modifies the second one, and then expects the stories to show up in the order 2-1-3. However, since Geeklog does not have the concept of a "last-modified" date for stories, we would have to modify the creation date of the story to pass this test. Which would mean that any change to a story through an Atompub client would cause the story to show up as "new" on the site, even if someone only fixed a typo in an old story.

Other than that detail, the Atompub implementation for stories is also fully compliant.