Discovery Resources Core Service

This document describes a set of capabilities that enable programmatic clients to navigate the Open Services for Lifecycle Collaboration URL space and discover provided services. This is accomplished using the following discoverable resources:

• An Atom Service Document at /jazz/atomsvc.xml which provides:
  • Collection descriptions for system-defined collections (change-events, indexing-rules and users).
  • Service descriptions (an extension to the Atom specification) for system-defined services (query and search).
• Provide OpenSearch Description Documents for the search and query services.

Motivation

A programmatic client needs to be able to discover key services automatically and without user intervention. The following diagram demonstrates the network of resources and links that allow clients to navigate an Open Services for Lifecycle Collaboration server programmatically.

Specification

This specification consists of the following components: a root Atom Service Document, search and query Opensearch Description Documents and finally the resource root Atom Service Document.

Root Atom Service Document

To provide an initial bootstrap entry point for clients Open Services for Lifecycle Collaboration provides an Atom Service Document at the root of the Open Services for Lifecycle Collaboration URL namespace, namely the /jazz segment. This service document provides an entry for each of the Open Services for Lifecycle Collaboration Core (system-defined) collections. Each collection is guaranteed to have a unique Atom category, to allow a client to programmatically identify the collection without using names or other ambiguous or potentially localizable property. This allows a client to point to /jazz/atomsvc.xml and discover these services and from here to link to other services/collections.

The following is an example service document provided at /jazz.

<?xml version="1.0" encoding="utf-8"?>
<service xmlns="http://www.w3.org/2007/app" 
         xmlns:atom="http://www.w3.org/2005/Atom"
         xmlns:osalm="http://example.org/xmlns/openservices/v0.6">
  <workspace>
    <atom:title>Open Services for Lifecycle Collaboration</atom:title>
    
    <collection href="/jazz/users">
      <atom:title>osalm Users</atom:title>
      <accept>application/atom+xml</accept>
      <atom:category term="users"
        scheme="http://example.org/categories/osalm/v0.6" />
      <categories fixed="yes" 
        scheme="http://example.org/categories/osalm/v0.6">
        <atom:category term="user"/>
      </categories>
    </collection>
    
    <collection href="/jazz/services/changeevents">
      <atom:title>osalm Change Events</atom:title>
      <accept>application/atom+xml</accept>
      <atom:category term="change-events"
        scheme="http://example.org/categories/osalm/v0.6" />
      <categories fixed="yes" 
        scheme="http://example.org/categories/osalm/v0.6">
        <atom:category term="change-event"/>
      </categories>
    </collection>
    
    <collection href="/jazz/indexing-rules">
      <atom:title>osalm Indexing Rules</atom:title>
      <accept>application/atom+xml</accept>
      <atom:category term="indexing-rules"
        scheme="http://example.org/categories/osalm/v0.6" />
      <categories fixed="yes" 
        scheme="http://example.org/categories/osalm/v0.6">
        <atom:category term="change-event"/>
      </categories>
    </collection>

    <osalm:service href="/jazz/resources">
      <atom:title>Resource Root</atom:title>
      <atom:category term="resource"
        scheme="http://example.org/categories/osalm/v0.6" />
    </osalm:service>

    <osalm:service href="/jazz/services/query">
      <atom:title>Query Service</atom:title>
      <atom:category term="query"
        scheme="http://example.org/categories/osalm/v0.6" />
    </osalm:service>

    <osalm:service href="/jazz/services/search">
      <atom:title>Search Service</atom:title>
      <atom:category term="search"
        scheme="http://example.org/categories/osalm/v0.6" />
    </osalm:service>

  </workspace>
</service>

Notes:

1. The content-type for the Atom Service Document is application/atomsvc+xml.
2. As the Service Document does not allow update it does not support/have revisions.
3. There is only one workspace element per service document.
4. System-defined collections are categorized using the standard Atom category scheme, as follows:
   • {scheme}#change-events - the Open Services for Lifecycle Collaboration change-event collection (commonly refered to as {change-event-feed}).
   • {scheme}#indexing-rules - the Open Services for Lifecycle Collaboration indexing rules collection (commonly refered to as {indexing-root}).
   • {scheme}#users - the Open Services for Lifecycle Collaboration users collection (commonly refered to as {users-feed}).
5. System-defined services are categorized using the standard Atom category scheme, as follows:
   • {scheme}#resource - the Open Services for Lifecycle Collaboration simple and collection resource storage root (commonly refered to as {resource-url}).
   • {scheme}#query - the Open Services for Lifecycle Collaboration query service (commonly refered to as {query-url}).
   • {scheme}#search - the Open Services for Lifecycle Collaboration search service (commonly refered to as {search-url}).
6. A server is at liberty to set specific cache expiration and cache control headers for a root service document as it is unlikely to change frequently.

Query and Search OpenSearch Description Documents

Example full-text search OpenSearch description document.

 
<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
   <ShortName>Drake Search</ShortName>
   <LongName>Drake Search</LongName>
   <Description>Search the Drake Resource Repository</Description>
   <Url type="application/atom+xml"
     template="http://localhost:8082/jazz/services/search?q={searchTerms}"/>
   <Query role="example" searchTerms="cat" />
   <Language>en-us</Language>
   <OutputEncoding>UTF-8</OutputEncoding>
   <InputEncoding>UTF-8</InputEncoding>
</OpenSearchDescription>

Resource Root Atom Service Document

Requests directly to the resource root URL will respond with an Atom Service Document that includes a listing of all Atom collections created with the collection storage API and marked as "published". Note that the current specifications here do not provide an API for marking collections for publication - this will be added in the future.

 
<?xml version="1.0" encoding="utf-8"?>
<service xmlns="http://www.w3.org/2007/app" 
         xmlns:atom="http://www.w3.org/2005/Atom">
  <workspace>
    <atom:title>Open Services for Lifecycle Collaboration - Resource Root</atom:title>

  </workspace>
</service>

Examples

This example follows the navigation steps required to provide an a tree view of the server for an admin user interface. The following is an outline of the activities which will be detailed in the following section.

• The client only needs to know the base URL for the top-level service document, for example http://localhost:9080/jazz.
• The client retrieves the service document, and is able to populate level-1 of the tree view with the collections "Users", "Change-Events" and "Indexing Rules". Each entry is identified, or understood, by the client based upon it's published category.
• For the users collection, level-2 is simply the contents of the Atom feed at the URL provided in the service document.
• For the change-events collection, level-2 should display the URL of the collection, but it is impractical to display all change-events.
• For the indexing roles collection, level-2 is simply the contents of the Atom feed at the URL provided in the service document.
• Level-2 will also include the links to services listed in the service document, search, query, resources, etc.

Additional nodes found in the service document can be rendered in a neutral manner if the category is unknown.