Architecture Management ATOM Result Sets

1.0 SPECIFICATION

In keeping with our architectural principals all query results will be returned in the form of an ATOM collection or feed.

The ATOM specification is flexible and we must state which fields are required and optional.

Service providers MAY extend a feed with any content they wish provided it does so within the rules and guidelines of the ATOM paging specification. Extensions defining new vocabularies MUST use XML namespaces.

Feed

Each Feed MUST include the proper namespace declarations (ATOM, Open Search, OSLC).

Each Feed MUST include

• opensearch:totalResults - element which specifies the total number of results found.
• atom:updated - the date/time the collection was created.
• atom:id - MUST be a URN(used in paging)
• atom:link - rel=self a reference back to the query
• atom:title - a human readable label for the feed (required by ATOM specification)

Example

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" 
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:dc="http://purl.org/dc/terms/"
      xmlns:oslc="http://open-services.net/xmlns/common/1.0/">

    <title>Query results</title>
    <id>urn:uuid:0003939e0af6</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <opensearch:totalResults>2</opensearch:totalResults>

    <entry>   
    ...
    </entry>
    ...

</feed>

Entry

Each Entry MUST include the following fields:

• atom:id - a URN id of the entry
• atom:title - with a human readable label of the entry
• atom:link - the absolute URI referencing the resource identified by the entry
• atom:updated - the datetime of the last modification of the resource

Example

<entry>
   <id>urn:uuid:23892382s7a7</id>
   <updated>2003-12-13T18:30:02Z</updated>
   <title>this is a title</title>
   <link href="http://example.org/resources/res158"/>
</entry> 

Service providers MAY include:

• oslc:etag - the etag value associated with the resource identified in the entry.
• atom:content - includes OSLC AM representation of the resource

Example

<entry>
   <id>urn:uuid:8s23ks8aksd8</id>
   <updated>2003-12-13T18:30:02Z</updated>
   <title>ICustomerAudit</title>
   <link href="http://example.org/resources/res9276"/>
   <oslc:etag>scmSBvo1Ed6LKdTEkaDiws</oslc:etag>
   <content>
       <rdf:RDF>
           <rdf:Description>
               <dc:title>IAudit</dc:title>
               <dc:description>Used to access customer audit information.</dc:description>
               <dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
               <dc:format>application/x-uml+xml</dc:format>
           </rdf:Description>               
       </rdf:RDF>
   </content>       
</entry>

A full complete example

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" 
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:dc="http://purl.org/dc/terms/"
      xmlns:oslc="http://open-services.net/xmlns/common/1.0/">

    <title>Query results</title>
    <id>urn:uuid:0003939e0af6</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <opensearch:totalResults>2</opensearch:totalResults>

    <entry>
       <id>urn:uuid:23892382s7a7</id>
       <updated>2003-12-13T18:30:02Z</updated>
       <title>IAudit</title>
       <link href="http://example.org/resources/res912"/>
       <oslc:etag>scmSBvo1Ed6LKdTEkaDiws</oslc:etag>
       <content>
           <rdf:RDF>
               <rdf:Description>
                   <dc:title>IAudit</dc:title>
                   <dc:description>Used to access audit information.</dc:description>
                   <dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
                   <dc:format>application/x-uml+xml</dc:format>
               </rdf:Description>               
           </rdf:RDF>
       </content>       
    </entry>

    <entry>
       <id>urn:uuid:8a93227fff7as</id>
       <updated>2003-12-13T18:30:02Z</updated>
       <title>ICustomerAudit</title>
       <link href="http://example.org/resources/res9276"/>
       <oslc:etag>scmSBvo1Ed6LKdTEkaDiws</oslc:etag>
       <content>
           <rdf:RDF>
               <rdf:Description>
                   <dc:title>ICustomerAudit</dc:title>
                   <dc:description>Used to access customer audit information.</dc:description>
                   <dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
                   <dc:format>application/x-uml+xml</dc:format>
               </rdf:Description>               
           </rdf:RDF>
       </content>       
    </entry>

</feed>
 

Paging

If the results to be returned in a collection exceed a prudent number of entries, a service provider MAY page the collection. Clients SHOULD be prepared to accept and manage paged collections.

The feed documents in a paged feed are tied together with the following <link> relations:

• rel="first" - A URI that refers to the first page in the set of pages.
• rel="last" - A URI that refers to the last page in the set of pages.
• rel="previous" - A URI that refers to the page just before the current page in the total set of pages.
• rel="next" - A URI that refers to the page just after current page in the total set of pages.

Paged feed collections MUST have at least one of these link relations and SHOULD contain as many as practical and applicable.

In the following example the <link> relations are direct child elements of the root <feed> element.

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" 
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:oslc="http://open-services.net/xmlns/common/1.0/">
    <id>urn:uuid:0003939e0af6</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <opensearch:totalResults>200</opensearch:totalResults>
    <link rel="first" href="http://example.com/query?id=2923&page=1" />
    <link rel="prev" href="http://example.com/query?id=2923&page=4" />
    <link rel="next" href="http://example.com/query?id=2923&page=6" />
    <link rel="last" href="http://example.com/query?id=2923&page=20" />

    <entry>
      ...
    </entry>

     ...

</feed>