Utilisation d'ATOM/APP en tant que format d'entrée et de sortie

Le service REST distant pour PUMA utilise le protocole de publication de document APP (ATOM Publishing Protocol) en tant que format d'entrée et de sortie principal. Celui-ci encapsule les éléments décrits par le document de schéma du service REST distant pour PUMA dans des documents de flux ou d'entrée ATOM appropriés. Bien qu'il s'agisse du format d'entrée et de sortie par défaut, le client doit spécifier le type MIME application/atom+xml dans le paramètre de requête mime-type ou bien dans l'en-tête d'acceptation. Cette rubrique fournit divers exemples et une description du mappage APP avec l'interface RESTful.

Pour plus d'informations sur le protocole APP, reportez-vous à sa documentation provisoire sur Internet.

Représentation des listes de résultats en tant que flux ATOM

Toutes les opérations du service REST renvoyant des listes de ressources retournent un document de flux ATOM représentant chaque ressource de portail sous forme d'entrée ATOM unique. Ceci s'applique aux cas d'utilisation de GET pour les opérations /um/attributes/users, /um/attributes/groups, /um/users/profiles et /um/groups/profiles. Selon la valeur du paramètre expandRefs, les entrées ATOM contiennent une section content qui encapsule la représentation XML de la ressource d'après le schéma défini dans l'interface.

Exemple 1 : cet exemple présente la réponse du serveur au chemin d'URI /um/secure/attributes/groups :

<?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>

Remarque : L'élément atom:updated ne contient aucune information utile mais il doit être ajouté pour conformité avec la spécification ATOM.

Exemple 2 : le même URI incluant l'option de développement des références, à savoir /um/secure/attributes/groups?expandRefs=true, retourne la réponse suivante du serveur :

<?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>

Représentation de ressources en tant qu'entrées ATOM

Toutes les ressources particulières sont représentées dans un document d'entrée ATOM. Cela s'applique aux cas d'utilisation de GET pour les opérations /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 et /um/groupmembership/unique_id_of_group. Cela signifie que la structure XML est encapsulée dans l'élément atom:content d'un élément atom:entry. De la sorte, des méta-informations utiles, comme le lien vers la ressource et son ID, peuvent être retournés de pair avec la ressource elle-même. Notez que la liste d'appartenance à des groupes est également traitée comme une ressource unique contenant les informations d'appartenance à des groupes d'un utilisateur ou d'un groupe.

L'exemple suivant extrait une profil utilisateur directement depuis la sortie basée ATOM. Il illustre une fonctionnalité accessoire commode de l'implémentation : comme ATOM vous permet d'ajouter plusieurs éléments atom:link à certains types, l'élément de liaison related peut être utilisé en tant que raccourci vers l'URL d'appartenance à des groupes de ce même utilisateur. Ce raccourci est fourni pour les profils d'utilisateur et de groupe et permet au client de suivre ce lien directement au lieu de construire l'URL à partir de ses parties statiques et dynamiques.

<?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>

Résultats pour une recherche paginée

Les résultats d'une recherche paginée vont contenir 3 éléments openSearch, un lien vers la première page et la dernière page, et si disponible, des liens vers la page précédente et la page suivante.

<?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>

Cas d'utilisation de POST, PUT et DELETE

Pour les opérations de l'interface du service PUMA SPI REST utilisant l'une des méthodes POST, PUT, ou DELETE, vous n'avez rien de particulier à prendre en compte pour utiliser le format APP depuis une perspective client. Vous pouvez utiliser le schéma XML ordinaire tel que défini dans le schéma ; vous n'avez pas à l'encapsuler dans des éléments ATOM lors d'opérations POST ou PUT des ressources vers le serveur. Le client doit veiller à ce que les espaces nom et la syntaxe corrects soient utilisés dans les entrées postées sur le serveur car celui-ci valide à la fois le format de la charge définie dans um.xsd et les structures ATOM élémentaires. Cette validation n'est pas particulièrement stricte mais les éléments non définis dans la spécification ATOM sont rejetés. Le client doit par conséquent vérifier ce qui suit dans la réponse :

Les opérations de flux POST ayant abouti renvoient une réponse avec un code statut 201 Created, l'en-tête Location défini à l'URI de la nouvelle ressource et une représentation de l'élément atom:entry qui vient d'être créé. Cela ne s'applique qu'aux opérations /um/users/profiles et /um/groups/profiles .
Les opérations PUT ou DELETE ayant abouti renvoient le code statut 200 OK.