View source for 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 [http://www.ietf.org/internet-drafts/draft-ietf-atompub-protocol-17.txt 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:

<pre>PLG_invokeService($plugin, $verb, $input, $output, $svc_msg);</pre>

{| border="0"
|<code>$plugin</code> || The plugin whose function needs to be invoked
|-valign="top"
|<code>$verb</code>   || The action to be performed ('post,' 'delete,' etc.)
|-valign="top"
|<code>$input</code>  || An array of input parameters<br>
Some of these input parameters may be optional, depending on the plugin. The plugin MUST ignore unknown parameters.
|-valign="top"
|<code>$output</code> || 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.
|-valign="top"
|<code>$svc_msg</code> || 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)

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

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:

{| border="0"
|-valign="top"
|<code>submit</code> || 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 '<tt>HTTP/1.1 201 Created</tt>' response or a '<tt>HTTP/1.1 200 Ok</tt>' response to the Atom client.
|-valign="top"
|<code>delete</code> || This verb deletes a specified resource on the server.
|-valign="top"
|<code>get</code>    || 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)