Developer Guide

Apache Roller

Version X

Original text is copyright © 2002-2004 David M Johnson

Contributors: Roller team and Sun Microsystems, Inc.

Table of Contents

1 - Introduction	3

2 - Atom Publishing Protocol	3

3 - Atom Admin Publishing Protocol	3

3.1 - Overview	3

3.2 - Installation / Configuration	3

3.3 - Authentication	4

3.4 - Protocol	4

3.4.1 - Introspection Endpoint	4

3.4.2 - User Endpoint	5

3.4.3 - Weblog Endpoint	6

3.4.4 - Member Endpoint	7

3.5 - Roller AAPP SDK	8

3.6 - Roller Examples	9

Introduction

This developer guide describes the developer components of Roller. These include:

Atom Publishing Protocol (AAP)

Atom Admin Publishing Protocol (AAPP)

Atom Publishing Protocol

TODO.

Atom Admin Publishing Protocol

Overview

The Atom Admin Publishing Protocol (AAPP) is a web service protocol that allows administration of weblog server resources, including:

Users

Weblogs

Weblog membership

The web service is implemented as XML over HTTP, employing the standard HTTP verb set: GET is used to fetch the description of an existing resource, POST creates a new resource, PUT modifies an existing resource, and DELETE deletes a resource. This is the same model employed by the Atom Publishing Protocol (APP).

AAPP is not directly related to APP; it is not part of the APP specification. While the features defined by AAPP were originally envisioned as part of the APP specification, the scope of the possible functions that could be encompassed in a weblog server administration protocol were too large to be considered for APP 1.0. Future versions of the APP specification should be expanded to encompass the features defined in AAPP.

The implementation of AAPP in Roller is experimental. The details of the protocol and the implementation may change in future releases without maintaining backwards compatibility.

Installation / Configuration

By default, the AAPP endpoint is disabled in Roller. To enable it, set the Roller configuration property webservices.adminprotocol.enable to true in your roller-custom.properties, and restart the web container.

Enabling the AAPP endpoint should not be taken lightly. AAPP grants a remote user (with the proper credentials) many powerful administrative functions. Make sure you understand the implications of this before you enable the endpoint.

Authentication

The roller AAPP endpoints use HTTP basic authentication. The authenticating user must have the Roller ADMIN role to use the AAPP endpoints.

Protocol

Every AAPP-accessible resource in the weblog server has an associated AAPP URL endpoint, and that endpoint is described by the href attribute on the XML description of the resource. The resource is accessed by executing one of the four standard HTTP verbs on the endpoint. For example a user resource is deleted by executing a DELETE on it's endpoint. A weblog resource is modified by executing a PUT on it's the weblog endpoint, etc.

Not all verbs make sense for all endpoints. For example, DELETE /roller/aapp/users is not allowed. If it was to do anything, intuitively, it would delete all of the users in the weblog server, which is not something that should be possible, for obvious reasons. The sections below describe which verbs can be applied to what endpoints.

Weblog resources are described as collections on entries. For example, the weblog collection contains zero or more weblog entries. AAPP endpoints can either target a collection or an entry. For example: GET /roller/users targets the user collection; it returns the set of all user entries. GET /roller/users/jtb targets the user entry “jtb”; it returns a singleton entry set containing one user entry.

The protocol makes use of the standard HTTP status codes:

Status Code	Condition
200 (OK)	GET, PUT, DELETE success
201 (CREATED)	POST success
404 (NOT FOUND)	GET, PUT, DELETE resource not found
400 (BAD REQUEST)	Invalid syntax in request
401 (UNAUTHORIZED)	User authentication failed
405 (METHOD NOT ALLOWED)	Authenticating user does not have permission to use endpoint
500 (INTERNAL SERVER ERROR)	Unhandled error in server

Discovery Endpoint

The discovery endpoint is used to discover the URL endpoints for accessing weblog server resources. Clients execute a GET on the discovery endpoint to retrieve the AAPP introspection document. For example:

[jtb@punk::~] authget.sh jtb <password> http://suntoy:8080/roller/aapp

<?xml version="1.0" encoding="UTF-8"?>

<service xmlns="http://purl.org/atom/aapp#">

<workspace title="Workspace: Collections for administration">

<collection title="Collection: Weblog administration entries" href="http://suntoy:8080/roller/aapp/weblogs">

<member-type>weblog</member-type>

</collection>

<collection title="Collection: User administration entries" href="http://suntoy:8080/roller/aapp/users">

<member-type>user</member-type>

</collection>

<collection title="Collection: Member administration entries" href="http://suntoy:8080/roller/aapp/members">

<member-type>member</member-type>

</collection>

</workspace>

</service>

The introspection document contains one or more workspaces, which in turn describe collections of resources. Because of the simplicity of the protocol, there is not much to describe. An AAPP introspection collection defines the resource type being described in its member-type sub element, and an href. The href is the endpoint used to access the resources of this type. For example, in the above example, the endpoint for the user resource type is: http://suntoy:8080/roller/aapp/users. This is very similar to and modeled after the APP introspection document.

The collection types defined by this protocol are: user, weblog, and member. AAPP implementations may support a subset of these (Roller supports all of them). The concepts of user and weblog resources are straightforward, but a member resource may not be as clear. A member resource is a triple consisting of a weblog handle, a user name, and a permission. A member resource therefore describes a user's permission for a particular weblog. These resource types will be discussed in detail later.

User Endpoint

The default AAPP user endpoint in Roller is: /roller/aapp/users. Clients use this to access user resources in the weblog server.

User Verbs

Clients access user resources in the weblog server by applying the HTTP verbs to the user AAPP endpoint:

GET /roller/aapp/users lists all user entries. There is no paging; all entries are returned.

GET /roller/aapp/users/<userName> lists the single user entry for the user name userName.

POST /roller/aapp/users creates new user entries. The users are described by the XML content. The XML content may contain one or more user entries. The new user entries are returned.

PUT /roller/aapp/users/<userName> updates the user entry for userName if present in the URI, or otherwise expects the user name to be present in the XML content. If the user name is specified in both places, they must match. The XML content may only contain one user entry. The updated user entry is returned.

PUT /roller/aapp/users updates existing user entries. The users are described by the XML content. Unlike the PUTting to an entry endpoint, the user entries in the XML content must contain user names. The updated user entries are returned.

DELETE /roller/aapp/users/<userName> deletes user entry userName. The deleted entry is returned.

User Schema

User entries have the following fields:

name

full-name

password

email-address

locale

timezone

date-created

For example:

<?xml version="1.0" encoding="UTF-8"?>

<users xmlns="http://purl.org/atom/aapp#" href="http://suntoy:8080/roller/aapp/users">

<user href="http://suntoy:8080/roller/aapp/users/jtb">

<name>jtb</name>

<full-name>Jeffrey Blattman</full-name>

<password>iplanet</password>

<locale>en</locale>

<timezone>US/Pacific</timezone>

<email-address>Jeffrey.Blattman@Sun.COM</email-address>

<date-created>1141863448000</date-created>

</user>

</users>

The date-created field is the output of the Java method Date.getTime(), which is the number of milliseconds since January 1, 1970, 00:00:00 GMT. It is returned from the GET verb; it is ignored as input to the POST and PUT verbs.

The locale field is a locale string as would be returned from the Java Locale.toString() method, which is <lang>[_<country>[_<variant>]].

The timezone field is a timezone ID string as would be returned from the Java TimeZone.getID() method, or as would be accepted as input to the TimeZone.getTimeZone() method.

The password field in only accepted as input to the POST and PUT verbs. It is never returned as output.

Weblog Endpoint

The default AAPP weblog endpoint in Roller is: /roller/aapp/weblogs. Clients use this to access user resources in the weblog server.

Weblog Verbs

GET /roller/aapp/weblogs lists all weblog entries. There is no paging; all weblog entries are returned.

GET /roller/aapp/weblogs/<handle> lists the single weblog entry for the weblog handle handle.

POST /roller/aapp/weblogs creates new weblog entries. The weblogs are described by the XML content. The XML content may contain one or more weblog entries. The new weblog entries are returned.

PUT /roller/aapp/weblogs/<handle> updates the weblog entry for handle if present in the URI, or otherwise expects the handle to be present in the XML content. If the handle is specified in both places, they must match. The XML content may only contain one weblog entry. The updated entry is returned.

PUT /roller/aapp/weblogs updates existing weblog entries. The weblogs are described by the XML content. Unlike the PUTting to an entry endpoint, the weblog entries in the XML content must contain handles. The updated weblog entries are returned.

DELETE /roller/aapp/weblogs/<handle> deletes the weblog entry with handle handle. The deleted entry is returned.

Weblog Schema

Weblog entries have the following fields:

handle

name

description

email-address

locale

timezone

date-created

creating-user

For example:

<?xml version="1.0" encoding="UTF-8"?>

<weblogs xmlns="http://purl.org/atom/aapp#" href="http://suntoy:8080/roller/aapp/weblogs">

<weblog href="http://suntoy:8080/roller/aapp/weblogs/junkyard">

<handle>junkyard</handle>

<name>Jeff's Jovial Junkyard</name>

<description>A place for garbage</description>

<locale>en</locale>

<timezone>US/Pacific</timezone>

<creating-user>jtb</creating-user>

<email-address>Jeffrey.Blattman@Sun.COM</email-address>

<date-created>1141863708000</date-created>

</weblog>

</weblogs>

The date-created field is only returned from the GET verb; it is ignored as input to the POST and PUT verbs. Its value is the output of the Java method Date.getTime(), which is the number of milliseconds since January 1, 1970, 00:00:00 GMT.

The locale field expects a locale string as would be returned from the Java Locale.toString() method, which is <lang>[_<country>[_<variant>]].

The timezone field expects a timezone ID string as would be returned from the Java TimeZone.getID() method, or as would be accepted as input to the TimeZone.getTimeZone() method.

Member Endpoint

The default AAPP weblog endpoint in Roller is: /roller/aapp/member. Clients use this to access member resources in the weblog server.

Member Verbs

Clients access member resources in the weblog server by applying the HTTP verbs to the user AAPP endpoint:

GET /roller/aapp/members lists all member entries in the weblog server. There is no paging; all entries are returned.

GET /roller/aapp/members/<handle> returns all member entries for the weblog handle handle.

GET /roller/aapp/members/<handle>/<userName> returns the single member entry for weblog handle handle and user name userName.

POST /roller/aapp/members creates a new member entry in the weblog server. The member entry is described by the XML content. The new member entry is returned.

PUT /roller/aapp/members[/<handle>][/<userName>]] updates the member entry for weblog handle handle and user name userName. If handle or userName are not present in the URI, they are taken from the XML content. If the weblog handle and user name are specified in both the URI and the XML content, they must match.

DELETE /roller/aapp/members/<handle>/<userName> deletes the member entry identifed by handle handle and user name userName. The deleted entry is returned.

Member URIs are slightly different than those for user and weblog resources. Where user and weblog entries are unqiuely identified by a single field, member entries are indentified by a user name – weblog handle tuple.

Member Schema

A member entry is a triple consisting of a user name, weblog handle, and a permission. The existence of the given member entry grants the user the given permission to the weblog.

Member entries have the following fields:

name

handle

permission

For Roller, the possible permission values are LIMITED, AUTHOR, and ADMIN. LIMITED permission indicates that the user can only post draft weblog entries. AUTHOR permission allows the user to post entries to the weblog. A user with ADMIN permission can modify meta information about the weblog such as the weblog name and description.

For example:

<?xml version="1.0" encoding="UTF-8"?>

<members xmlns="http://purl.org/atom/aapp#" href="http://suntoy:8080/roller/aapp/members">

<member href="http://suntoy:8080/roller/aapp/members/junkyard/jtb">

<name>jtb</name>

<handle>junkyard</handle>

<permission>ADMIN</permission>

</member>

</members>

The name and handle fields must identify existing user and weblog resources, respectively. The permission field must be the string ADMIN, AUTHOR, or LIMITED (case is not relevant).

Roller AAPP SDK

The Roller AAPP SDK consists of a set of classes that facilitate marshalling and unmarshalling the various entry and collection object types. Essentially, the SDK is a set of beans. XML content can be unmarshalled by constructing the various beans with an XML stream or a JDOM document / element. The bean objects can be marshalled by calling a toDocument() method that returns a JDOM document representation of the bean.

The AAPP SDK does not include utilities to assist in making wire connections to the AAPP server. Because AAPP is based on the standard HTTP verbs, there are many existing methods for accomplishing this. The Jakarta Commons HTTP Client library offers a simple and robust solution.

For details on the AAPP SDK, refer to the javadocs.

TODO: make the javadocs available w/ the product, or tell how to get them.

Roller Examples

TODO. describe sample .xml files. Should we include HTTP verb library in the SDK?

Dave Johnson

2005-12-09T11:50:02