WebSphere Portal - How the portal implements the Remote PUMA SPI REST Service

This to be filed in the "I'm sure this'll be useful someday" pile 

...

describe the general part of the Remote PUMA SPI REST Service Interface. This interface can be implemented by different providers that can be based on different backend systems or user repositories and provide their own input and output formats. The implementation of the interface described here is the one based on WebSphere Portal Beta. 

The implementation described here uses ATOM (refer to RFC 4287) and the ATOM Publishing Protocol as basic input and output format to wrap the resource representations described by the schema in the general part. Additionally, using the portal Remote PUMA SPI REST Service requires that you consider some special aspects described in this section: -

URL path segment for virtual portals

WebSphere Portal provides the concept of virtual portals that allows you to manage several separate portals within one portal installation. You can associate each of these virtual portals with a user realm and thereby limit the scope of users or groups that can access it to one realm of the underlying user repository.

Identifiers used in the Portal Implementation

For the unique identifier in the URLs, the portal uses a string representation of the internal identifier that is considered to be opaque to the client. The identifier that is used for retrieval of users or groups, that is by either the identifier or the memberOf request parameters, is the unique security name that is associated to the security context in the WebSphere Application Server. The exact matching of the unique security name is part of the security configuration, but in most scenarios it matches the distinguished name (DN). The same identifier is of course also used for the identifier attribute in the profile element. 

Access Control Checks

The portal does not allow you to set permissions for attribute definitions. Therefore the Remote PUMA SPI REST Service allows requests to some operations only for authenticated users.

Using ATOM/APP as input and output format

The portal Remote PUMA SPI REST Service uses the ATOM Publishing Protocol (APP) as the primary input and output format. It wraps the elements described by the schema document in the Remote PUMA SPI REST Service in appropriate ATOM feed or entry documents. Although this is the default input and output format, the client should specify the mime type application/atom+xml either in the mime-type request parameter or in the accept header. A more detailed description of how the APP maps to the RESTful interface and some examples are given here.

Switch for tunneling of HTTP methods

The portal implementation allows you to simulate PUT and DELETE requests by tunneling, that is by using POST requests instead. 

HTTP caching

The Remote PUMA SPI REST Service sets the Cache-Control HTTP header in the response to public for resources that are served without authentication, and to private for URIs that require authentication.

Context Root and Authentication Mechanism

The Remote PUMA SPI REST Service is implemented as a servlet that runs as a separate enterprise application on the WebSphere Portal server.

Lookup Facility in the portal

For both convenience and alignment to other portal REST services, the portal Remote PUMA SPI REST Service offers a lookup facility. This is done by plugging a provider into a reusable lookup facility in the portal. This functionality allows you to retrieve particular URLs of the service by specifying an absolute URI as a parameter to the so-called lookup servlet addressed by /wps/poc.

...

Taken from the WebSphere Portal Beta wiki here.