Using ATOM/APP as input and output format | HCL Digital Experience
The remote REST service for PUMA 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 REST service for PUMA 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.
For details about the APP refer to the draft for the protocol on the internet.
Representing list results as ATOM feeds
All the REST service operations that return lists of resources return an ATOM feed document that
represents each portal resource as a single ATOM entry. This applies to the GET
cases for the operations /um/attributes/users
,
/um/attributes/groups
, /um/users/profiles
, and /um/groups/profiles
. Depending on the value of the expandRefs
parameter, the ATOM entries contain a content
section that embeds the XML representation of
the resource according to the schema defined in the interface.
/um/secure/attributes/groups
URI path:
<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:xs="http://www.w3.org/2001/XMLSchema-datatypes"
xmlns:um="http://www.ibm.com/xmlns/prod/websphere/um.xsd"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<atom:title>Available group attributes</atom:title>
<atom:author>
<atom:name>IBM WebSphere Portal</atom:name>
</atom:author>
<atom:link href="/wps/um/secure/attributes/groups" rel="self"/>
<atom:id>um:secure/attributes/groups</atom:id>
<atom:updated>2006-12-16T17:06:35.609Z</atom:updated>
<atom:entry>
<atom:title>cn</atom:title>
<atom:link href="/wps/um/secure/attributes/groups/cn" rel="self"/>
<atom:id>um:secure/attributes/groups/cn</atom:id>
<atom:updated>2006-12-16T17:06:35.609Z</atom:updated>
</atom:entry>
<atom:entry>
<atom:title>description</atom:title>
<atom:link href="/wps/um/secure/attributes/groups/description" rel="self"/>
<atom:id>um:secure/attributes/groups/description</atom:id>
<atom:updated>2006-12-16T17:06:35.609Z</atom:updated>
</atom:entry>
<atom:entry>
<atom:title>createTimestamp</atom:title>
<atom:link href="/wps/um/secure/attributes/groups/createTimestamp" rel="self"/>
<atom:id>um:secure/attributes/groups/createTimestamp</atom:id>
<atom:updated>2006-12-16T17:06:35.609Z</atom:updated>
</atom:entry>
<atom:entry>
<atom:title>modifyTimestamp</atom:title>
<atom:link href="/wps/um/secure/attributes/groups/modifyTimestamp" rel="self"/>
<atom:id>um:secure/attributes/groups/modifyTimestamp</atom:id>
<atom:updated>2006-12-16T17:06:35.609Z</atom:updated>
</atom:entry>
</atom:feed>
atom:updated
does not contain any useful
information, but it has to be added to comply to the ATOM specification.
/um/secure/attributes/groups?expandRefs=true
, gives the
following server response:
<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:xs="http://www.w3.org/2001/XMLSchema-datatypes"
xmlns:um="http://www.ibm.com/xmlns/prod/websphere/um.xsd"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<atom:title>Available group attributes</atom:title>
<atom:author>
<atom:name>IBM WebSphere Portal</atom:name>
</atom:author>
<atom:link href="/wps/um/secure/attributes/groups?expandRefs=true" rel="self"/>
<atom:id>um:secure/attributes/groups%3FexpandRefs%3Dtrue</atom:id>
<atom:updated>2006-12-16T17:15:23.391Z</atom:updated>
<atom:entry>
<atom:title>cn</atom:title>
<atom:link href="/wps/um/secure/attributes/groups/cn" rel="self"/>
<atom:id>um:secure/attributes/groups/cn</atom:id>
<atom:updated>2006-12-16T17:15:23.391Z</atom:updated>
<atom:content type="application/xml">
<um:attribute xmlns:um="um" name="cn"
type="xs:string" multiValued="false"/>
</atom:content>
</atom:entry>
<atom:entry>
<atom:title>description</atom:title>
<atom:link href="/wps/um/secure/attributes/groups/description" rel="self"/>
<atom:id>um:secure/attributes/groups/description</atom:id>
<atom:updated>2006-12-16T17:15:23.391Z</atom:updated>
<atom:content type="application/xml">
<um:attribute xmlns:um="um" name="description"
type="xs:string" multiValued="true"/>
</atom:content>
</atom:entry>
<atom:entry>
<atom:title>createTimestamp</atom:title>
<atom:link href="/wps/um/secure/attributes/groups/createTimestamp" rel="self"/>
<atom:id>um:secure/attributes/groups/createTimestamp</atom:id>
<atom:updated>2006-12-16T17:15:23.391Z</atom:updated>
<atom:content type="application/xml">
<um:attribute xmlns:um="um" name="createTimestamp"
type="xs:dateTime" multiValued="false"/>
</atom:content>
</atom:entry>
<atom:entry>
<atom:title>modifyTimestamp</atom:title>
<atom:link href="/wps/um/secure/attributes/groups/modifyTimestamp" rel="self"/>
<atom:id>um:secure/attributes/groups/modifyTimestamp</atom:id>
<atom:updated>2006-12-16T17:15:23.391Z</atom:updated>
<atom:content type="application/xml">
<um:attribute xmlns:um="um" name="modifyTimestamp"
type="xs:dateTime" multiValued="false"/>
</atom:content>
</atom:entry>
</atom:feed>
Representing resources as ATOM entries
All particular resources are represented in an ATOM entry document. This applies to the GET cases
for the operations /um/attributes/users/attribute
name
, /um/attributes/groups/attribute name
, /um/currentuser/profile
, /um/users/profiles/unique_id_of_user
, /um/groups/profiles/unique_id_of_group
, /um/groupmembership/unique_id_of_user
, and /um/groupmembership/unique_id_of_group
. This means
that the XML structure is wrapped in the atom:content
element of one atom:entry
element. This way useful meta information, such as the link to the resource and an
ID can be returned together with the resource itself. Note that the group membership
list is also treated as a single resource that contains the group membership
information of one user or group.
atom:link
elements with certain types, the
related
link element can be used for a shortcut
to the group membership URL of the same user. This shortcut is provided for user and
group profiles and allows the client to directly follow this link instead of
constructing the URL from static and dynamic parts.
<?xml version="1.0" encoding="UTF-8"?>
<atom:entry xmlns:xs="http://www.w3.org/2001/XMLSchema-datatypes"
xmlns:um="http://www.ibm.com/xmlns/prod/websphere/um.xsd"
xmlns:atom="http://www.w3.org/2005/Atom">
<atom:title>wpsadmin</atom:title>
<atom:link href="/wps/um/secure/users/profiles/9eAe . . . K5D1" rel="self"/>
<atom:link href="/wps/um/secure/groupmembership/9eA . . . K5D1" rel="related"/>
<atom:id>um:secure/users/profiles/9eAeK2IIK9L59QKQ2 . . . K5D1</atom:id>
<atom:updated>2006-12-16T17:34:04.406Z</atom:updated>
<atom:content type="application/xml">
<um:profile type="user" identifier="uid=wpsadmin,o=defaultWIMFileBasedRealm">
<um:attribute name="uid" type="xs:string" multiValued="false">
<um:attributeValue>wpsadmin</um:attributeValue>
</um:attribute>
<um:attribute name="cn" type="xs:string" multiValued="false">
<um:attributeValue>wpsadmin</um:attributeValue>
</um:attribute>
</um:profile>
</atom:content>
</atom:entry>
Result for a paged search
<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:xs="http://www.w3.org/2001/XMLSchema-datatypes"
xmlns:um="http://www.ibm.com/xmlns/prod/websphere/um.xsd"
xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<atom:title>User profiles</atom:title>
<atom:author>
<atom:name>IBM WebSphere Portal</atom:name>
</atom:author>
<atom:link href="/wps/um/secure/users/profiles?
resultsPerPage=2&searchAttributes=uid
%3DtestUser*&includeAttributes=uid&pageHandle=4d793b59" rel="self"/>
<atom:id>um:secure/users/profiles%3FresultsPerPage%3D2%26searchAttributes
%3Duid%
3DtestUser*%26includeAttributes%3Duid%26pageHandle%3D4d793b59</atom:id>
<atom:updated>2009-02-25T13:13:12.296Z</atom:updated>
<atom:link href="/wps/um/secure/users/profiles?
resultsPerPage=2&searchAttributes=uid
%3DtestUser*&includeAttributes=uid&pageHandle=4d793b59&page=1"
rel="first"/>
<atom:link href="/wps/um/secure/users/profiles?
resultsPerPage=2&searchAttributes=uid
%3DtestUser*&includeAttributes=uid&pageHandle=4d793b59&page=3"
rel="last"/>
<atom:link href="/wps/um/secure/users/profiles?
resultsPerPage=2&searchAttributes=uid
%3DtestUser*&includeAttributes=uid&pageHandle=4d793b59&page=2"
rel="next"/>
<opensearch:totalresults>5</opensearch:totalresults>
<opensearch:startindex>1</opensearch:startindex>
<opensearch:itemsperpage>2</opensearch:itemsperpage>
<atom:entry>
<atom:title>uid=testUser5,o=defaultWIMFileBasedRealm</atom:title>
<atom:link
href="/wps/um/secure/users/profiles/9eAeK9OCJR07M1D0JMG65BOCJMG6NHP8MM4C43EGJMKC
43D83JHC5RD66R4713" rel="self"/>
<atom:link
href="/wps/um/secure/groupmembership/9eAeK9OCJR07M1D0JMG65BOCJMG6NHP8MM4C43EGJMK
C43D83JHC5RD66R4713" rel="related"/>
<atom:id>um:secure/users/profiles/9eAe
K9OCJR07M1D0JMG65BOCJMG6NHP8MM4C43EGJMKC43D83JHC5RD66R4713</atom:id>
<atom:updated>2009-02-25T13:13:12.296Z</atom:updated>
<atom:content type="application/xml">
<um:profile type="user"
identifier="uid=testUser5,o=defaultWIMFileBasedRealm">
<um:attribute name="uid" type="xs:string" multivalued="false">
<um:attributevalue>testUser5</um:attributevalue>
</um:attribute>
</um:profile>
</atom:content>
</atom:entry>
POST, PUT and DELETE cases
um.xsd
and the basic ATOM structures. This is not very strict, but
elements that are not defined in the ATOM specification are rejected. The client
should therefore check the response as follows: - Successful POST operations to feeds return a response with status code
201 Created
, theLocation
header set to the URI of the new resource, and a representation of theatom:entry
element that has been created. This is only the case for operations/um/users/profiles
and/um/groups/profiles
- Successful PUT or DELETE operations return a status code of
200 OK
.