Join Now
Quality Rating:
  • Currently 0.0 / 5
(0.0 / 5 - 0 votes cast)
Expertise Level:
  • Currently 0.0 / 5
(0.0 / 5 - 0 votes cast)

This page was last modified 23:34, 17 March 2008.

Atom API for Nokia MOSH

From Forum Nokia Wiki

Notes:

  • This document has been auto-generated from HTML source, so some formatting problems are present.
  • This is a DRAFT document describing a web service that hasn't been launched yet. We are making this available so we can hear your comments and so you can peek at what's coming around the corner. The API will be live at some point this semester.
  • When the API is live, it may not implement all the features described here. We are taking a phased approach and will roll features out as they're ready. We will update this document to reflect what is available versus what is still in development.
  • If you have any questions or comments, please feel free to add notes on the "comment" tab above - your feedback is much appreciated!

Cheers,
 The MOSH Team.

Contents

Abstract

The Atom application programming interface (API) for Nokia MOSH implements the Atom Publishing Protocol (RFC 5023) as a mechanism for distributing and publishing content on the MOSH platform. This document specifies the Atom API for MOSH.

1 Copyright

Copyright 2008 Nokia Corporation. All rights reserved.

Nokia and Forum Nokia are trademarks or registered trademarks of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other product and company names mentioned herein may be trademarks or trade names of their respective owners.

Disclaimer

The information in this document is provided "as is," with no warranties whatsoever, including any warranty of merchantability, fitness for any particular purpose, or any warranty otherwise arising out of any proposal, specification, or sample. This document is provided for informational purposes only.

Nokia Corporation disclaims all liability, including liability for infringement of any proprietary rights, relating to implementation of information presented in this document. Nokia Corporation does not warrant or represent that such use will not infringe such rights.

Nokia Corporation retains the right to make changes to this document at any time, without notice.

License

A license is hereby granted to download and print a copy of this document for personal use only. No other license to any other intellectual property rights is granted herein.

2 Introduction

MOSH is a one-to-many distribution platform €“ a targeted channel for developers and tech leaders to publish applications and other content for any mobile device to a global audience. The Nokia MOSH application programming interface (API) implements the Atom Publishing Protocol as a mechanism for publishing, editing, and distributing content on the MOSH platform.

[#RFC5023 The Atom Publishing Protocol] [RFC5023] is an application-level protocol for publishing and editing Web Resources using [#RFC2616 HTTP] [RFC2616] and [#W3C.REC-xml XML 1.0] [W3C.REC-xml]. The MOSH API, coupled with Atom, supports the creation of Web Resources and provides facilities for:

  • Authentication: Ownership of and access to manipulate resources.
  • Collections: Sets of Resources, which can be retrieved in whole or in part.
  • Services: Discovery and description of Collections.
  • Editing: Creating, editing, and deleting Resources.

3 Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [#RFC2119 RFC 2119] [RFC2119].

4 Terminology

For convenience, this application programming interface can be referred to as the "MOSH API." Where disambiguation is required, "Atom API for MOSH" may be used to refer to this particular specification. The term "Lifeblog API for MOSH" refers to [#lifeblog Section 16] of this specification.

In addition to the terminology described in Section 3 of the [#RFC5023 Atom Publishing Protocol] [RFC5023], this specification uses the following terminology:

  • Client - A Client is any application that makes requests to the MOSH API.
  • content item - An application, audio file, document, game, graphic, or video uploaded to MOSH and represented as an Atom Entry.
  • Collection - This specification uses Collection in the Atom Protocol sense to describe a Resource that contains a set of Member Resources. Collections are represented as Atom Feeds. See Section 9 of [#RFC5023 [RFC5023]]. This term is uppercased when referring to a Collection in the Atom sense.
  • collection - MOSH uses the term "collection" to refer to a user-organized collection of content items. This specification refers to the MOSH definition of this word when this term is lowercased. At times this specification uses the phrase "user collection" or "user-collected content" in reference to this term.
  • people - This term is synonymous with "users."
  • Seek - Seek allows MOSH users to make requests for content they want and don't see on MOSH. The community can then respond with suggestions or custom created content answering the Seek.
  • Service - The system that encompasses the MOSH API, acting as a service provider to Clients.
  • tag - A tag is a free-form descriptive label added to a content item or Seek intended to add description and/or categorization to the content.

5 Location and Versioning

While this document defines the Atom API for MOSH, the MOSH API may be expanded in the future to include other kinds of APIs. The initial URI for all MOSH APIs is:

https://mosh-api/

NOTE
This URI is temporary. A new URI will be announced when the Service launches.

The Atom API for MOSH is located below this URI. Furthermore, the MOSH API is versioned. That is, it defines a specific URI for each version of the API. Thus, the URI for version 1.0 of the Atom API for MOSH is:

https://mosh-api/atom/1.0

Except where otherwise specified, all URIs in this specification are assumed to be located below this URI.

The URI for the MOSH API contains only the programming interface to MOSH. It does not contain any developer documentation. All developer documentation for the MOSH API is located at:

http://mosh-developer/

NOTE
This URI is temporary. A new URI will be announced when the Service launches.

6 Namespaces

While the MOSH API does not define a specific MOSH namespace, MOSH API XML Documents MUST be "namespace-well-formed" as specified in Section 7 of [#W3C.REC-xml-names [W3C.REC-xml-names]]. [#table_namespaces []] lists those namespaces used in MOSH API XML Documents. These namespace prefixes are not semantically significant.

Prefix Namespace Reference
app: http://www.w3.org/2007/app

[#RFC5023 [RFC5023]]

atom: http://www.w3.org/2005/Atom

[#RFC4287 [RFC4287]]

dcterms: http://purl.org/dc/terms/

[#RFC5013 [RFC5013]]

opensearch: http://a9.com/-/spec/opensearch/1.1/

[#OSEARCH [OSEARCH]]

referrer: http://a9.com/-/opensearch/extensions/referrer/1.0/

[#OSEARCH [OSEARCH]]

parameters: http://a9.com/-/spec/opensearch/extensions/parameters/1.0/

[#OSEARCH [OSEARCH]]

relevance: http://a9.com/-/opensearch/extensions/relevance/1.0/

[#OSEARCH [OSEARCH]]

The "app:" prefix is used for elements defined in the Atom Protocol. The "atom:" prefix describes elements defined by the Atom Syndication Format. This specification uses several metadata elements from the Dublin Core Metadata set of terms. This is a recognizable and standard format for describing metadata. The "dcterms:" prefix is used for these elements. Likewise, the OpenSearch data format defines elements commonly used in search results. This specification uses the prefix "opensearch:" for elements defined by the OpenSearch standard. The OpenSearch standard defines several extensions to itself. Of these, the MOSH API uses the "referrer:", "parameters:", and "relevance:" prefixes.

7 Documents

7.1 Service Document

Section 8 of [#RFC5023 [RFC5023]] describes the use of Service Documents to expose the capabilities and locations of the available Collections in the Service. The MOSH API provides one Service Document exposing all Collections within the MOSH platform. The MOSH API Service Document is located at:

https://mosh-api/atom/1.0

When a Service Document is requested, the Service MUST respond with an HTTP Content-Type header of:

application/atomsvc xml;charset=utf-8

7.1.1 Element Definitions

Element definitions listed here are intended to augment the definitions in Section 8.3 of [#RFC5023 [RFC5023]]. Where the MOSH API does not define a Service Document element, please defer to the Atom Protocol for the full definition.

7.1.1.1 The "app:workspace" Element

The MOSH API uses Workspaces in the Service Document as a way to logically separate groups of Collections. Currently, there are only two groups of Collections. The first Workspace lists the main group of Collection endpoints, while the second Workspace lists all Collections of content types.

The presence of multiple Workspaces does not imply any specific processing assumptions.

7.1.1.2 The "app:collection" Element

The app:collection element describes a Collection by specifically providing the URI for the Atom Feed that represents the Collection. The app:accept element in the app:collection elements defines acceptable content types for creating new Entries in the Collection.

The presence of a value in the app:accept element indicates that the value of the app:collection "href" attribute accepts POST requests to create new Entries in the Collection. The content type indicated by the app:accept element SHOULD be the content type of any new Entries posted to the Collection. The app:categories indicates the acceptable categories for use with new Entries. If an app:accept element appears but contains no value, then the Collection does not accept POST requests.

7.1.2 Example 

<?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>Nokia MOSH</atom:title>
    <collection href="https://mosh-api/atom/1.0/content">
      <atom:title>Content</atom:title>
      <categories
        href="https://mosh-api/atom/1.0/categories/types"/>
      <accept>application/atom xml;type=entry</accept>
    </collection>
    <collection href="https://mosh-api/atom/1.0/collections">
      <atom:title>Collections</atom:title>
      <accept>application/atom xml;type=entry</accept>
    </collection>
    <collection href="https://mosh-api/atom/1.0/users">
      <atom:title>People</atom:title>
      <accept/>
    </collection>
    <collection href="https://mosh-api/atom/1.0/tags">
      <atom:title>Tags</atom:title>
      <accept/>
    </collection>
    <collection href="https://mosh-api/atom/1.0/seeks">
      <atom:title>Seeks</atom:title>
      <categories
        href="https://mosh-api/atom/1.0/categories/types"/>
      <accept>application/atom xml;type=entry</accept>
    </collection>
  </workspace>
  <workspace>
    <atom:title>Nokia MOSH: Content</atom:title>
    <collection href="https://mosh-api/atom/1.0/content/applications">
      <atom:title>Applications</atom:title>
      <categories fixed="yes">
        <atom:category
          scheme="https://mosh-api/atom/1.0/categories/types"
          term="1"
          label="application"/>
      </categories>
      <accept>application/atom xml;type=entry</accept>
    </collection>
    <collection href="https://mosh-api/atom/1.0/content/games">
      <atom:title>Games</atom:title>
      <categories fixed="yes">
        <atom:category
          scheme="https://mosh-api/atom/1.0/categories/types"
          term="2"
          label="game"/>
      </categories>
      <accept>application/atom xml;type=entry</accept>
    </collection>
    <collection href="https://mosh-api/atom/1.0/content/audio">
      <atom:title>Audio</atom:title>
      <categories fixed="yes">
        <atom:category
          scheme="https://mosh-api/atom/1.0/categories/types"
          term="3"
          label="audio"/>
      </categories>
      <accept>application/atom xml;type=entry</accept>
    </collection>
    <collection href="https://mosh-api/atom/1.0/content/video">
      <atom:title>Video</atom:title>
      <categories fixed="yes">
        <atom:category
          scheme="https://mosh-api/atom/1.0/categories/types"
          term="4"
          label="video"/>
      </categories>
      <accept>application/atom xml;type=entry</accept>
    </collection>
    <collection href="https://mosh-api/atom/1.0/content/graphics">
      <atom:title>Graphics</atom:title>
      <categories fixed="yes">
        <atom:category
          scheme="https://mosh-api/atom/1.0/categories/types"
          term="5"
          label="graphic"/>
      </categories>
      <accept>application/atom xml;type=entry</accept>
    </collection>
    <collection href="https://mosh-api/atom/1.0/content/documents">
      <atom:title>Documents</atom:title>
      <categories fixed="yes">
        <atom:category
          scheme="https://mosh-api/atom/1.0/categories/types"
          term="6"
          label="document"/>
      </categories>
      <accept>application/atom xml;type=entry</accept>
    </collection>
  </workspace>
</service>

Figure 1: Service Document

7.2 Category Document

When a Category Document is requested, the Service MUST respond with an HTTP Content-Type header of:

application/atomcat xml;charset=utf-8

The MOSH API has Category Documents for MOSH content types and API errors. The first describes each of the standard MOSH content types. The latter describes all error types that may be returned by the API. These Category Documents are located at:

https://mosh-api/atom/1.0/categories/types
https://mosh-api/atom/1.0/categories/errors

See [#error_codes_apx []] for a list of all error codes to included in the errors Category Document.

7.2.1 Example 

<?xml version="1.0" encoding="utf-8"?>
<app:categories
    xmlns:app="http://www.w3.org/2007/app"
    xmlns:atom="http://www.w3.org/2005/Atom"
    fixed="yes"
    scheme="https://mosh-api/atom/1.0/categories/types">
  <atom:category term="1" label="application"/>
  <atom:category term="2" label="game"/>
  <atom:category term="3" label="audio"/>
  <atom:category term="4" label="video"/>
  <atom:category term="5" label="graphic"/>
  <atom:category term="6" label="document"/>
</app:categories>

Figure 2: Category Document

This example presents the Category Document as it conforms to Section 7 of the [#RFC5023 Atom Protocol] [RFC5023]. The "term" attribute here equates to the category ID, while the "label" is the human-readable category name.

7.2.2 Usage

The Category Document is used primarily when creating content. Note that the "fixed" attribute is set to "yes," indicating that the list is a fixed set. Third-parties MUST NOT use a category not found in this list. Unrecognized categories will be discarded by the Service and may result in a 400 Bad Request response including an error document in the body of the response to describe the error. See [#errors Section 14] for more information on error handling.

7.3 Collection Document

When a Collection Document is requested, the Service MUST respond with an HTTP Content-Type header of:

application/atom xml;type=feed;charset=utf-8

7.3.1 Element Definitions

Element definitions listed here are intended to augment the definitions in Section 4 of [#RFC4287 [RFC4287]]. Where the MOSH API does not define a Collection Document element, please defer to the Atom Syndication Format for the full definition.

7.3.1.1 The "app:collection" Element

When an app:collection element appears in a Collection Document, it indicates the URI that may be used to POST new Entries to the Collection. The use of the app:collection element as described for Service Documents in [#app_collection Section 7.1.1.2] applies here.

7.3.1.2 The "opensearch:" Elements

Collections returned by the MOSH API are often paginated recordsets containing many more pages of data. In the event of a paginated Collection, the Collection Document will contain multiple atom:link elements indicating "first," "previous," "next," and "last" relationships. In addition, the MOSH API utilizes the [#OSEARCH OpenSearch specification] [OSEARCH] to describe the total number of items in the Collection, the number of items per "page," and the starting index of the current "page." OpenSearch defines the opensearch:totalResults, opensearch:itemsPerPage, and opensearch:startIndex elements to describe this data.

7.3.1.3 The "app:edited" Element

Section 10.2 of [#RFC5023 [RFC5023]] specifies that Entries appearing in Collection Documents SHOULD contain one app:edited element. This element is used to differentiate between semantically significant updates (with the atom:updated element) and any change, no matter how minor it may be.

Since MOSH does not make a distinction between these two types of changes, both the atom:updated and app:edited elements will usually contain the same value. This specification does not limit the System from changing this practice in the future to represent significant vs. minor changes with these elements.

In addition, Section 10 of the Atom Protocol specifies that Entries within an Atom Feed SHOULD be ordered by the app:edited element, with the most recently edited Entries coming first in the document order.

7.3.2 Example 

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:app="http://www.w3.org/2007/app"
      xmlns:dcterms="http://purl.org/dc/terms/"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">

  <title>Nokia MOSH: Content</title>
  <updated>2008-01-22T17:08:33Z</updated>
  <id>tag:mosh.nokia.com,2008-03:atom/1.0/content</id>
  <app:collection href="https://mosh-api/atom/1.0/content">
    <title>Content</title>
    <app:categories
      href="https://mosh-api/atom/1.0/categories/types"/>
    <app:accept>application/atom xml;type=entry</app:accept>
  </app:collection>
  <link rel="self" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/content?idx=13"/>
  <link rel="first" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/content"/>
  <link rel="previous" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/content?idx=1"/>
  <link rel="next" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/content?idx=25"/>
  <link rel="last" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/content?idx=48336"/>
  <link rel="alternate" type="text/html"
    href="http://mosh.nokia.com/browse"/>
  <link rel="mobile" type="text/html"
    href="http://mosh.nokia.mobi/browse/all/recent"/>
  <link rel="search"
    href="https://mosh-api/atom/1.0/search/description"
    title="Content Search"/>
  <opensearch:totalResults>48344</opensearch:totalResults>
  <opensearch:itemsPerPage>12</opensearch:itemsPerPage>
  <opensearch:startIndex>13</opensearch:startIndex>
  <generator uri="https://mosh-api/">Nokia MOSH</generator>

  <entry>
    <title>Soccer Game</title>
    <link rel="self"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/content/{GUID}"/>
    <link rel="edit"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/content/{GUID}"/>
    <link rel="related"
      type="application/atom xml;type=feed"
      href="https://mosh-api/atom/1.0/users/ramsey/uploads"/>
    <link rel="comments"
      type="application/atom xml;type=feed"
      href="https://mosh-api/atom/1.0/content/{GUID}/comments"/>
    <link rel="alternate"
      type="text/html"
      href="http://mosh.nokia.com/u/ramsey/c19"/>
    <link rel="mobile"
      type="text/html"
      href="http://mosh.nokia.mobi/u/ramsey/c19"/>
    <id>tag:mosh.nokia.com,2008-01-22:atom/1.0/content/{GUID}</id>
    <published>2008-01-22T17:08:33Z</published>
    <updated>2008-01-22T17:08:33Z</updated>
    <app:edited>2008-01-22T17:08:33Z</app:edited>
    <category
      scheme="https://mosh-api/atom/1.0/categories/types"
      term="2"
      label="game"/>
    <author>
      <name>ramsey</name>
      <uri>https://mosh-api/atom/1.0/users/ramsey</uri>
    </author>
    <summary>
      j2me game
    </summary>
    <content type="application/java-archive"
      src="http://mosh.nokia.com/u/ramsey/c19/downloadFile" />
    <dcterms:title>Soccer.jar</dcterms:title>
    <dcterms:subject>soccer</dcterms:subject>
    <dcterms:subject>game</dcterms:subject>
  </entry>

</feed>

Figure 3: Collection Document

7.4 Entry Document

When an Entry Document is requested, the Service MUST respond with an HTTP Content-Type header of:

application/atom xml;type=entry;charset=utf-8

7.4.1 Element Definitions

Element definitions listed here are intended to augment the definitions in Section 4 of [#RFC4287 [RFC4287]]. Where the MOSH API does not define an Entry Document element, please defer to the Atom Syndication Format for the full definition.

7.4.1.1 The "atom:link" Element

All atom:link elements in the Entry document follow the same rules as described in [#RFC4287 [RFC4287]]. It does, however, bear repeating that Section 11.1 of [#RFC5023 [RFC5023]] defines the "edit" link relation. When the "edit" link relation is present, the href URI can be used to retrieve (GET), update (PUT), and delete (DELETE) the Resource represented by that Entry.

7.4.1.2 The "atom:summary" Element

The atom:summary element provides the short description of content items, user collections, and Seeks and the tagline for users.

The MOSH API deviates from [#RFC4287 [RFC4287]] in that the atom:summary element is OPTIONAL in most cases. This is due to business rules surrounding the nature of descriptions for content items, people, and collections in which the description is optional. However, for the same reason, the atom:summary element is REQUIRED for Seeks, since the description is mandatory, according to MOSH business rules.

7.4.1.3 The "atom:content" Element

The atom:content element plays different roles depending on the Entry Document in which it is contained. For content items retrieved with GET, this element contains a "src" attribute with a URI to the downloadable content item file. However, when creating a new content item with POST, this element MUST conform to the rules defined in [#resource_edit Section 8.1]. When updating a content item with PUT, this element is OPTIONAL. User collection Entries and Seek Entries contain this element with a "src" attribute whose URI points to an Atom Feed of content items. Error Entry Documents SHOULD contain this element to provide a description of the error (see [#errors Section 14]). User Entry Documents MAY contain this element to provide the user's personal description of themselves. Comment Entries contain this element to provide the text of the comment.

7.4.1.4 The "dcterms:title" Element

Since many Entry Documents on the MOSH platform represent content items, it is necessary to describe the file name of the content item. To describe the content item file name, the MOSH API uses the dcterms:title element from the [#RFC5013 Dublin Core Metadata] [RFC5013] set of terms.

7.4.1.5 The "dcterms:subject" Element

Some Entry Documents representing data in the MOSH platform need to describe "tags" (or descriptive keywords) that are set on an item such as a content item or collection. To describe this data, the MOSH API uses the dcterms:subject element from the [#RFC5013 Dublin Core Metadata] [RFC5013] set of terms.

Each tag MAY be contained in a separate dcterms:subject element, or the dcterms:subject element MAY contain a space-separated list of tags.

The MOSH API does not support the use of compound tags, that is, tags containing multiple words or phrases. MOSH tags are alpha-numeric words that MAY contain dashes (-) or underscores (_) but MUST NOT contain spaces. If a tag contains a space, then the MOSH API will consider each separate word as a separate tag.

7.4.2 Example 

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:app="http://www.w3.org/2007/app"
       xmlns:dcterms="http://purl.org/dc/terms/">
  <title>Soccer Game</title>
  <link rel="self"
    type="application/atom xml;type=entry"
    href="https://mosh-api/atom/1.0/content/{GUID}"/>
  <link rel="edit"
    type="application/atom xml;type=entry"
    href="https://mosh-api/atom/1.0/content/{GUID}"/>
  <link rel="related"
    type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/users/ramsey/uploads"/>
  <link rel="comments"
    type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/content/{GUID}/comments"/>
  <link rel="alternate"
    type="text/html"
    href="http://mosh.nokia.com/u/ramsey/c19"/>
  <link rel="mobile"
    type="text/html"
    href="http://mosh.nokia.mobi/u/ramsey/c19"/>
  <id>tag:mosh.nokia.com,2008-01-22:atom/1.0/content/{GUID}</id>
  <published>2008-01-22T17:08:33Z</published>
  <updated>2008-01-22T17:08:33Z</updated>
  <category
    scheme="https://mosh-api/atom/1.0/categories/types"
    term="2"
    label="game"/>
  <author>
    <name>ramsey</name>
    <uri>https://mosh-api/atom/1.0/users/ramsey</uri>
  </author>
  <summary>
    j2me game
  </summary>
  <content type="application/java-archive"
    src="http://mosh.nokia.com/u/ramsey/c19/downloadFile"/>
  <dcterms:title>Soccer.jar</dcterms:title>
  <dcterms:subject>soccer</dcterms:subject>
  <dcterms:subject>game</dcterms:subject>
</entry>

Figure 4: Entry Document

8 Publishing Resources

With regard to publishing and manipulating Entry Resources, the MOSH API adheres to Section 4.3 of [#RFC5023 [RFC5023]]. That is, the following considerations are taken into account when using HTTP requests to access Resources:

  • GET retrieves a known Resource. A successful request returns a 200 OK status code with an entity body representing the resource.
  • POST creates a new Resource when an Atom Entry representation is posted to a Collection. The MOSH API differs from [#RFC5023 [RFC5023]] in that Clients SHOULD NOT submit non-Atom-Entry representations to a Collection. In the event the system receives a representation other than an Atom Entry, it will respond with a 415 Unsupported Media Type response and an appropriate Error Entry (see [#acceptable_types Section 8.2] and [#errors Section 14]). A successful request returns a 201 Created status code with a Location header containing the URI to the new Resource, a Content-Location header with the same exact URI, and a complete representation of the new Entry in the entity body (see Section 9.2 of [#RFC5023 [RFC5023]]).
  • PUT is used to edit a known Resource. A successful request returns a 200 OK status code with an entity body representing the resource.
  • DELETE is used to remove a known Resource. A successful request returns a 204 No Content status code.

All other specifications defined in Sections 4 and 5 of [#RFC5023 [RFC5023]] SHOULD be followed.

8.1 Creating or Editing Resources

When the MOSH API receives Entry Documents through a POST or PUT request, the MOSH API differs from Section 4.1.2 of the [#RFC4287 Atom Syndication Format] [RFC4287] as it pertains to the requirements on elements in the Entry Document.

Specifically, the MOSH API places the following restrictions and requirements on fields in Entry Documents received through POST or PUT:

  • The atom:entry element MUST contain exactly one atom:author element. If using PUT to modify the entry, the atom:author element MUST NOT change the author set on the Entry when it was created. The atom:author element MUST match the authenticated user identified by the X-WSSE username token (see [#wsse_authentication Section 13]). If it does not match, then the system MUST return a 403 Forbidden response with an appropriate error message as defined in [#errors Section 14].
  • For content items, the atom:entry element MUST contain exactly one atom:category element. If using PUT to modify the entry, the atom:category element MUST NOT change the category set on the Entry when it was created. The system will ignore any changes made to the atom:category element of a known Resource. Entries representing user collections SHOULD NOT contain atom:category elements. Entries representing Seeks MAY contain zero or more atom:category elements to indicate content types preferred in response to the Seek. All categories must adhere to the scheme https://mosh-api/atom/1.0/categories/types.
  • For content item Entries submitted with a POST request, the atom:entry element MUST contain exactly one atom:content element with a "type" attribute corresponding to the [#IANA IANA MIME Media Type] [IANA] of the content as defined in [#RFC2046 [RFC2046]]. The value of the atom:content element MUST be the full base64-encoded value (adhering to [#RFC2045 [RFC2045]] semantics) of the file being uploaded to the MOSH API as part of the Entry. User Entries MAY also contain an atom:content element to provide an OPTIONAL user description. If this element is present in a user Entry, its type MUST be "text." Other types of Entries in the MOSH API do not use this element.
  • The atom:entry element SHOULD contain exactly one dcterms:title element. Unlike the atom:title element, which provides a descriptive title of the Entry, the dcterms:title element, when present, describes the actual file name of a content item. If the Entry Document does not represent an uploaded content item, then this element SHOULD NOT be present. If the Entry Document does represent a content item and this element is not present, the MOSH API will dynamically create a file name for the content item based on the atom:title element. This, in particular, is for Lifeblog compatibility.
  • The atom:entry element MAY contain zero or more dcterms:subject elements. Each dcterms:subject element MAY contain multiple, space-separate tags (or keywords) describing the Entry. See [#dcterms_subject Section 7.4.1.5] for more information.
  • The atom:entry element MAY contain an atom:summary element to provide a short description (255 characters) of content items, user collections, and Seeks.
  • If the app:control element is present as a child of an atom:entry element and it contains an app:draft element with a value of "yes," then the Service MUST assume that the entity represented by the Entry is intended to be private and not accessible to users other than the authenticated content owner. If the app:draft element contains a value of "no" or is not present, then the system MUST assume that the entity represented is public.

8.2 Acceptable Media Types

The MOSH API accepts only the following media types for POST and PUT requests. If a Client submits a media type not accepted by the MOSH API, the Service MAY return a 415 Unsupported Media Type response with an appropriate error entity Entry (see [#errors Section 14]).

For forward compatibility and adherence to [#RFC5023 [RFC5023]], all Clients SHOULD submit request entities to the MOSH API with the following Content-Type header:

application/atom xml;type=entry

To fully support the Lifeblog Client the MOSH API Service MUST also accept the following media types:

application/atom xml
application/x.atom xml
application/xml

The body of the request SHOULD match that of the media type indicated in the Content-Type request header.

8.3 Authorization to Publish Content

Clients SHOULD submit only POST requests to Collection Documents that accept such requests to create Entries in that Collection (see [#app_collection Section 7.1.1.2] and [#colldoc_collection_element Section 7.3.1.1]). Likewise, Clients SHOULD submit only PUT or DELETE requests to Entry Documents that accept such requests (see [#atom_link_element Section 7.4.1.1]).

Furthermore, Clients SHOULD include in these requests an X-WSSE header as described in [#wsse_authentication Section 13]. If this header is not present, the system MUST NOT allow the Client to create, edit, or delete Resources. If it is present, but the authenticated user identified by the header does not have permission to create, edit, or delete a particular Resource, then the system MUST NOT allow the Client to create, edit, or delete the Resource.

8.4 Example

[#publish_example Figure 5] illustrates an example Entry Document to use for publishing content items to the MOSH API. 

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:dcterms="http://purl.org/dc/terms/">
  <title>MOSH favicon</title>
  <updated>2008-02-15T18:08:33Z</updated>
  <author>
    <name>ramsey</name>
  </author>
  <id>tag:mosh.nokia.com,2008-02-15:favicon.ico</id>
  <summary>
    The MOSH favicon
  </summary>
  <category
    scheme="https://mosh-api/atom/1.0/categories/types"
    term="5"
    label="graphic"/>
  <dcterms:title>favicon.ico</dcterms:title>
  <dcterms:subject>favicon</dcterms:subject>
  <dcterms:subject>mosh</dcterms:subject>
  <content type="image/x-icon">
AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAQAAAAAAAAAAAAAAAAA
AAAAAAD////9/////f////3w vD9n92f/VHDUf0Oqw79AKcA/QCnAP0Oqw79UcNR/Z/dn/3w vD9
/////f////3////9/////f////3f9N/9X8hf/QepB/0ApwD9CqoK/Se0J/0ntCf9CqoK/QCnAP0H
qQf9X8hf/d/03/3////9/////f////3f9N/9KrUq/QCnAP06uzr9mduZ/ff89/3////9/////ff8
9/2Z25n9Ors6/QCnAP0qtSr93/Tf/f////3w vD9X8hf/QCnAP1Gv0b93fPd/f3 /f3////9////
/f////3////9/f79/d3z3f1Gv0b9AKcA/V/IX/3w vD9n92f/QepB/06uzr9yOzI/dTw1P3p9 n9
9/z3/dvy2/3f9N/9 /37/eL14v3U8NT9z 7P/Tq7Ov0HqQf9n92f/VHDUf0ApwD9mduZ/ZPZk/0q
tSr9lNqU/dvy2/1NwU39X8hf/e347f1xznH9KrUq/bbltv2Z25n9AKcA/VHDUf0Oqw79CqoK/ff8
9/1/03/9AKcA/X/Tf/3U8NT9KrUq/T 9P/3p9 n9VMRU/QCnAP2p4an99/z3/QqqCv0Oqw79AKcA
/Se0J/3////9f9N//QCnAP1/03/91PDU/Sq1Kv0/vT/96ffp/VTEVP0ApwD9qeGp/f////0ntCf9
AKcA/QCnAP0ntCf9/////YPUg/0ApwD9eNB4/dLv0v0otSj9Ors6/eT15P1UxFT9AKcA/anhqf3/
///9J7Qn/QCnAP0Oqw79CqoK/ff89/2m4Kb9AKcA/Sq1Kv1oy2j9DKsM/ROtE/120Hb9I7Mj/QCn
AP2/6L/99/z3/QqqCv0Oqw79UcNR/QCnAP2Z25n99vv2/Ua/Rv0HqQf9AKcA/RivGP0Yrxj9AKcA
/QepB/1Rw1H9/f79/Znbmf0ApwD9UcNR/Z/dn/0HqQf9Ors6/d3z3f3i9eL9quGq/Y3Xjf3C6sL9
v m//YrWiv2q4ar95vbm/d3z3f06uzr9B6kH/Z/dn/3w vD9X8hf/QCnAP1Gv0b93fPd/f3 /f3/
///9/////f////3////9/f79/d3z3f1Gv0b9AKcA/V/IX/3w vD9/////d/03/0qtSr9AKcA/Tq7
Ov2Z25n99/z3/f////3////99/z3/Znbmf06uzr9AKcA/Sq1Kv3f9N/9/////f////3////93/Tf
/V/IX/0HqQf9AKcA/QqqCv0ntCf9J7Qn/QqqCv0ApwD9B6kH/V/IX/3f9N/9/////f////3////9
/////f////3w vD9n92f/VHDUf0Oqw79AKcA/QCnAP0Oqw79UcNR/Z/dn/3w vD9/////f////3/
///9AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAA==
  </content>
</entry>

Figure 5: Entry Document for Publishing Content Items

8.5 MOSH API Entry Document DTD

While the Atom Syndication Format and Atom Protocol do not define DTDs for the Atom formats, thus not requiring validity in the sense used by [#W3C.REC-xml [W3C.REC-xml]], the MOSH API does define a DTD for processing Entry documents submitted through POST and PUT requests.

All Entries submitted to the MOSH API MUST be valid, as defined by the MOSH API Entry document DTD. See [#entry_dtd []] for the DTD.

9 Consideration of Special Resources

There are some resources that deviate from the standard document descriptions found in [#documents_section Section 7]. This appendix describes those resources and how to represent them.

9.1 Collections and Entries of User Collections

A Collection Document of user collections is special because the Entries it contains actually represent other Collection Documents of user-collected content. Thus, these Entries are structured different than most other Entries in the MOSH API. There are no atom:category elements, and a atom:content element MUST be present with a "type" attribute of application/atom xml;type=feed and a "src" attribute containing a URI to a Collection Document representing this user collection. The description of the user collection is contained in the atom:summary element. These Entries are represented by Entry Documents at /collections/{GUID}, which may accept GET, PUT, and DELETE requests to modify the collection details, such as its title and description.

[#user_collections_fig Figure 6] illustrates how a Collection Document of user collections might appear. These types of Collection Documents are found at:

  • /collections
  • /content/{GUID}/collections
  • /users/{username}/collections

The app:collection element SHOULD appear only in the Collection Document for user collections at the /collections URI. This is the only URI at which the system will allow new user collections to be created with POST.

The Collection Document of user-collected content behaves in the same way as a standard Collection Document, described in [#collection_document Section 7.3]. These documents MUST contain an app:collection element, allowing the owner of the user collection to POST Entry representations of content items, adding the content to their user collection.

Collection Documents of user-collected content are located at:

  • /collections/{GUID}/content

Each content item in a user collection Collection MAY be referenced by /collections/{GUID}/content/{GUID}, which retrieves the content item's Entry Document, also located at /content/{GUID}. The URI for the content item in the Collection (/collections/{GUID}/content/{GUID}) MUST NOT accept PUT requests, but it MUST allow DELETE requests, which do not delete the content item, but, rather, remove the content item from the user's collection. 

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:app="http://www.w3.org/2007/app"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">

  <title>Nokia MOSH: Collections</title>
  <updated>2008-01-22T17:08:33Z</updated>
  <id>tag:mosh.nokia.com,2008-03:atom/1.0/collections</id>
  <app:collection href="https://mosh-api/atom/1.0/collections">
    <title>Collections</title>
    <app:accept>application/atom xml;type=entry</app:accept>
  </app:collection>
  <link rel="self" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/collections?idx=13"/>
  <link rel="first" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/collections"/>
  <link rel="previous" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/collections?idx=1"/>
  <link rel="next" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/collections?idx=25"/>
  <link rel="last" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/collections?idx=19224"/>
  <link rel="alternate" type="text/html"
    href="http://mosh.nokia.com/browse/collections"/>
  <link rel="mobile" type="text/html"
    href="http://mosh.nokia.mobi/browse/collections"/>
  <link rel="search"
    href="https://mosh-api/atom/1.0/search/description"
    title="Content Search"/>
  <opensearch:totalResults>19236</opensearch:totalResults>
  <opensearch:itemsPerPage>12</opensearch:itemsPerPage>
  <opensearch:startIndex>13</opensearch:startIndex>
  <generator uri="https://mosh-api/">Nokia MOSH</generator>

  <entry>
    <title>Funny Stuff</title>
    <link rel="self"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/collections/{GUID}"/>
    <link rel="edit"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/collections/{GUID}"/>
    <link rel="related"
      type="application/atom xml;type=feed"
      href="https://mosh-api/atom/1.0/users/ramsey/collections"/>
    <link rel="comments"
      type="application/atom xml;type=feed"
      href="https://mosh-api/atom/1.0/collections/{GUID}/comments"/>
    <link rel="alternate"
      type="text/html"
      href="http://mosh.nokia.com/collection/{GUID}"/>
    <link rel="mobile"
      type="text/html"
      href="http://mosh.nokia.mobi/collection/{GUID}"/>
    <id>tag:mosh.nokia.com,2008-03:atom/1.0/collections/{GUID}</id>
    <published>2008-01-22T17:08:33Z</published>
    <updated>2008-01-22T17:08:33Z</updated>
    <app:edited>2008-01-22T17:08:33Z</app:edited>
    <author>
      <name>ramsey</name>
      <uri>https://mosh-api/atom/1.0/users/ramsey</uri>
    </author>
    <summary>Funny stuff I find on MOSH</summary>
    <content type="application/atom xml;type=feed"
      src="https://mosh-api/atom/1.0/collections/{GUID}/content"/>
  </entry>

</feed>

Figure 6: Collection Document of User Collections

9.2 Comments Collections and Entries

The MOSH API represents comments on content items and users with the standard Collection and Entry documents described in [#collection_document Section 7.3] and [#entry_document Section 7.4]. However, it may not be readily clear how to represent comments. Thus, [#comments_fig Figure 7] illustrates a Collection Document for comments. Contained within it is an Entry to illustrate how comment Entries appear.

Comment Collection Documents are located at:

  • /content/{GUID}/comments
  • /users/{username}/comments

Comment Entry Documents are located at:

  • /content/{GUID}/comments/{GUID}
  • /users/{username}/comments/{GUID}

Clients MAY POST comment Entry representations to a comments Collection to add a comment to the content item or user to which the comments Collection belongs. Clients MAY DELETE a comment Entry if the authenticated user owns the comment. 

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:app="http://www.w3.org/2007/app"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">

  <title>Nokia MOSH: Comments for maggie</title>
  <updated>2008-01-22T17:08:33Z</updated>
  <id>tag:mosh.nokia.com,2008-03:atom/1.0/users/maggie/comments</id>
  <app:collection
    href="https://mosh-api/atom/1.0/users/maggie/comments">
    <title>Comments for maggie</title>
    <app:accept>application/atom xml;type=entry</app:accept>
  </app:collection>
  <link rel="related" type="application/atom xml;type=entry"
    href="https://mosh-api/atom/1.0/users/maggie"/>
  <link rel="self" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/users/maggie/comments?idx=13"/>
  <link rel="first" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/users/maggie/comments"/>
  <link rel="previous" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/users/maggie/comments?idx=1"/>
  <link rel="next" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/users/maggie/comments?idx=25"/>
  <link rel="last" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/users/maggie/comments?idx=64"/>
  <link rel="alternate" type="text/html"
    href="http://mosh.nokia.com/user/maggie"/>
  <link rel="mobile" type="text/html"
    href="http://mosh.nokia.mobi/user/maggie"/>
  <opensearch:totalResults>76</opensearch:totalResults>
  <opensearch:itemsPerPage>12</opensearch:itemsPerPage>
  <opensearch:startIndex>13</opensearch:startIndex>
  <generator uri="https://mosh-api/">Nokia MOSH</generator>

  <entry>
    <title>Comment</title>
    <link rel="self"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/users/maggie/comments/{GUID}"/>
    <link rel="edit"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/users/maggie/comments/{GUID}"/>
    <id>tag:mosh.nokia.com,2008-02-05:atom/1.0/users/maggie/comments/{GUID}</id>
    <published>2008-02-05T17:08:33Z</published>
    <updated>2008-02-05T17:08:33Z</updated>
    <app:edited>2008-01-22T17:08:33Z</app:edited>
    <author>
      <name>ramsey</name>
      <uri>https://mosh-api/atom/1.0/users/ramsey</uri>
    </author>
    <content type="text">
      zug zug!
    </content>
  </entry>

</feed>

Figure 7: Comments Collection Document

9.3 Seeks Collections and Entries

The MOSH API represents Seeks in much the same way as it represents user collections. Since a Seek represents a Collection of content items and comments, a Collection of Seeks must contain Entries of Seeks that reference the Collection for the content items and comments that are responses to the Seek.

For the sake of clarity, [#seeks_collection_fig Figure 8] illustrates how a Collection Document of Seeks might appear. These types of Collection Documents are found at:

  • /seeks
  • /content/{GUID}/seeks
  • /users/{username}/seeks

For all remaining behavior of Seeks Collections and Entries, refer to [#user_collections Section 9.1], since Seeks resources mimic the behavior of user collections.

Please note: a Collection of Seeks responses (represented by a resource at /seeks/{GUID}/responses) includes content item, user collection, and comment Entries. See [#comments Section 9.2] for details on the structure of comment Entries and [#user_collections Section 9.1] for user collection Entries. 

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:app="http://www.w3.org/2007/app"
      xmlns:dcterms="http://purl.org/dc/terms/"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">

  <title>Nokia MOSH: Seeks</title>
  <updated>2008-01-22T17:08:33Z</updated>
  <id>tag:mosh.nokia.com,2008-03:atom/1.0/seeks</id>
  <app:collection href="https://mosh-api/atom/1.0/seeks">
    <title>Seeks</title>
    <app:categories
      href="https://mosh-api/atom/1.0/categories/types"/>
    <app:accept>application/atom xml;type=entry</app:accept>
  </app:collection>
  <link rel="self" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/seeks?idx=13"/>
  <link rel="first" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/seeks"/>
  <link rel="previous" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/seeks?idx=1"/>
  <link rel="next" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/seeks?idx=25"/>
  <link rel="last" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/seeks?idx=19224"/>
  <link rel="alternate" type="text/html"
    href="http://mosh.nokia.com/browse/seeks"/>
  <link rel="mobile" type="text/html"
    href="http://mosh.nokia.mobi/browse/seeks/all"/>
  <link rel="search"
    href="https://mosh-api/atom/1.0/search/description"
    title="Content Search"/>
  <opensearch:totalResults>19236</opensearch:totalResults>
  <opensearch:itemsPerPage>12</opensearch:itemsPerPage>
  <opensearch:startIndex>13</opensearch:startIndex>
  <generator uri="https://mosh-api/">Nokia MOSH</generator>

  <entry>
    <title>The Meaning of Life</title>
    <link rel="self"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/seeks/{GUID}"/>
    <link rel="edit"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/seeks/{GUID}"/>
    <link rel="related"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/users/maggie/seeks"/>
    <link rel="alternate"
      type="text/html"
      href="http://mosh.nokia.com/seeks/{GUID}"/>
    <link rel="mobile"
      type="text/html"
      href="http://mosh.nokia.mobi/seeks/{GUID}"/>
    <id>tag:mosh.nokia.com,2008-03:atom/1.0/seeks/{GUID}</id>
    <published>2008-01-22T17:08:33Z</published>
    <updated>2008-01-22T17:08:33Z</updated>
    <app:edited>2008-01-22T17:08:33Z</app:edited>
    <author>
      <name>maggie</name>
      <uri>https://mosh-api/atom/1.0/users/maggie</uri>
    </author>
    <summary>The Meaning of Life, please.</summary>
    <content type="application/atom xml;type=feed"
      src="https://mosh-api/atom/1.0/seeks/{GUID}/responses"/>
    <dcterms:subject>life</dcterms:subject>
    <dcterms:subject>of</dcterms:subject>
    <dcterms:subject>meaning</dcterms:subject>
  </entry>

</feed>

Figure 8: Collection Document of Seeks

9.4 Collections and Entries of Users

The MOSH API represents users with the standard Collection and Entry documents described in [#collection_document Section 7.3] and [#entry_document Section 7.4]. However, it may not be readily clear how to represent users. Thus, [#users_fig Figure 9] illustrates a Collection Document for users. Contained within it is an Entry to illustrate how user Entries appear.

Users Collection Documents are located at:

  • /users
  • /users/{username}/people

User Entry Documents are located at:

  • /users/{username}
  • /users/{username}/people/{name}

Clients MAY POST user Entry representations to the Users Collection at /users/{username}/people to add users to {username}'s "My People." The Client MUST be authenticated and may add users only to the "My People" of the authenticated user. Likewise, Clients may send DELETE requests to /users/{username}/people/{name} to remove users from {name}'s "My People." 

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:app="http://www.w3.org/2007/app"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">

  <title>Nokia MOSH: People</title>
  <updated>2008-01-22T17:08:33Z</updated>
  <id>tag:mosh.nokia.com,2008-03:atom/1.0/users</id>
  <link rel="self" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/users?idx=13"/>
  <link rel="first" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/users"/>
  <link rel="previous" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/users?idx=1"/>
  <link rel="next" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/users?idx=25"/>
  <link rel="last" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/users?idx=203016"/>
  <link rel="alternate" type="text/html"
    href="http://mosh.nokia.com/browse/people"/>
  <link rel="mobile" type="text/html"
    href="http://mosh.nokia.mobi/browse/people"/>
  <opensearch:totalResults>203028</opensearch:totalResults>
  <opensearch:itemsPerPage>12</opensearch:itemsPerPage>
  <opensearch:startIndex>13</opensearch:startIndex>
  <generator uri="https://mosh-api/">Nokia MOSH</generator>

  <entry>
    <title>{username}</title>
    <link rel="self"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/users/{username}"/>
    <link rel="edit"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/users/{username}"/>
    <link rel="collections"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/users/{username}/collections"/>
    <link rel="comments"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/users/{username}/comments"/>
    <link rel="people"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/users/{username}/people"/>
    <link rel="seeks"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/users/{username}/seeks"/>
    <link rel="uploads"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/users/{username}/uploads"/>
    <link rel="enclosure"
      type="image/jpeg"
      length="13945"
      href="http://nds2.content.mosh.nokia.com/user/{GUID}/100x100.jpg"/>
    <link rel="alternate"
      type="text/html"
      href="http://mosh.nokia.com/user/{username}"/>
    <link rel="mobile"
      type="text/html"
      href="http://mosh.nokia.mobi/user/{username}"/>
    <id>tag:mosh.nokia.com,2008-02-05:atom/1.0/users/{username}</id>
    <published>2008-02-05T17:08:33Z</published>
    <updated>2008-02-05T17:08:33Z</updated>
    <app:edited>2008-01-22T17:08:33Z</app:edited>
    <author>
      <name>{username}</name>
      <uri>https://mosh-api/atom/1.0/users/{username}</uri>
    </author>
    <summary>User tagline</summary>
    <content type="text">
      User description
    </content>
  </entry>

</feed>

Figure 9: Users Collection Document

9.5 Tag Collections and Entries

The MOSH API represents tags in much the same way as it represents user collections and Seeks. Since a tag represents a Collection of content items, a Collection of tags must contain Entries of tags that reference the Collection for the content items that have been tagged with the tag. Refer to [#user_collections Section 9.1] for details on how to represent tags.

The tag URIs support only GET requests. Content item Entries may not be added directly to a tag Collection, nor may a tag Entry be updated. The MOSH API creates new tags when the dcterms:subject element is used on Entries that support tags.

The tag URIs are:

  • /tags
  • /tags/{tag}
  • /tags/{tag}/content

10 Searching MOSH

The MOSH API allows Clients to search MOSH through the API interface from the https://mosh-api/atom/1.0/search URI. The MOSH API utilizes conventions defined in [#OSEARCH OpenSearch 1.1 Draft 3] [OSEARCH] to accept search requests and return search results.

[#osearch_description_doc Section 10.1] details the OpenSearch Description Document that exposes the search capabilities of the MOSH API. Clients should use this document to discover the search URI and query parameters used in sending search requests. to the MOSH API. [#osearch_response_doc Section 10.2] describes the resulting Collection Document the MOSH API returns in response to search requests.

10.1 OpenSearch Description Document

The OpenSearch Description Document for the MOSH API is located at the following URI:

https://mosh-api/atom/1.0/search/description

When an OpenSearch Description Document is requested, the Service MUST respond with an HTTP Content-Type header of:

application/opensearchdescription xml;charset=utf-8

10.1.1 Autodiscovery of Search

Content Collection Documents will contain the following link element with a relation of "search." This will direct Clients to the OpenSearch Description Document for MOSH. 

<link rel="search"
  href="https://mosh-api/atom/1.0/search/description"
  title="Content Search"/>

Figure 10: Search Link

10.1.2 Example

The MOSH API OpenSearch Description Document follows the specification defined in [#OSEARCH [OSEARCH]]. [#opensearchdoc_fig Figure 11] illustrates the OpenSearch Description Document as the MOSH API returns it. Refer also to [#OSEARCH-Parameter [OSEARCH-Parameter]] and [#OSEARCH-Referrer [OSEARCH-Referrer]] for information on the "parameters:" and "referrer:" namespaces used in the MOSH API OpenSearch Description Document. 

<?xml version="1.0" encoding="utf-8"?>
<OpenSearchDescription
  xmlns="http://a9.com/-/spec/opensearch/1.1/"
  xmlns:referrer="http://a9.com/-/opensearch/extensions/referrer/1.0/">

  <ShortName>MOSH Search</ShortName>
  <Description>Search content in MOSH.</Description>
  <Tags>mosh content search</Tags>
  <Contact>russell@mosh.nokia.com</Contact>
  <Query role="example" searchTerms="graphic"/>
  <Image height="16" width="16" type="image/x-icon">
    http://mosh.nokia.com/favicon.ico
  </Image>
  <InputEncoding>UTF-8</InputEncoding>
  <OutputEncoding>UTF-8</OutputEncoding>
  <SyndicationRight>open</SyndicationRight>
  <Url xmlns:parameters=\
        "http://a9.com/-/spec/opensearch/extensions/parameters/1.0/"
      type="application/atom xml;type=feed"
      template="https://mosh-api/atom/1.0/search"
      parameters:method="GET">
    <parameters:Parameter name="q" value="{searchTerms}"/>
    <parameters:Parameter name="idx" value="{startIndex}" minimum="0"/>
    <parameters:Parameter name="src" value="{referrer:source}"
      minimum="0"/>
  </Url>

</OpenSearchDescription>

Figure 11: OpenSearch Description Document

10.2 OpenSearch Results Collection Document

The Collection Document returned as a response to a search request follows the same format as that described in [#collection_document Section 7.3] and [#RFC4287 [RFC4287]]. However, there are several OpenSearch response elements included in the Collection Document, as defined in [#OSEARCH [OSEARCH]]. These are opensearch:totalResults, opensearch:itemsPerPage, opensearch:startIndex, and opensearch:Query. In addition, a relevance:score element SHOULD be included in each atom:entry element in the Collection Document. The relevance:score element MUST follow the rules defined in [#OSEARCH-Relevance [OSEARCH-Relevance]].

The atom:id element contains the same tag value for all search results returned: tag:mosh.nokia.com,2008-03:atom/1.0/search.

[#search_results_fig Figure 12] illustrates a full example of the OpenSearch results Collection Document. 

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:app="http://www.w3.org/2007/app"
      xmlns:dcterms="http://purl.org/dc/terms/"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:relevance=\
        "http://a9.com/-/opensearch/extensions/relevance/1.0/">

  <title>Nokia MOSH: Search Results</title>
  <updated>2008-01-22T17:08:33Z</updated>
  <id>tag:mosh.nokia.com,2008-03:atom/1.0/search</id>
  <link rel="self" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/search?q=graphic&idx=13"/>
  <link rel="first" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/search?q=graphic"/>
  <link rel="previous" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/search?q=graphic&idx=1"/>
  <link rel="next" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/search?q=graphic&idx=25"/>
  <link rel="last" type="application/atom xml;type=feed"
    href="https://mosh-api/atom/1.0/search?q=graphic&idx=336"/>
  <link rel="alternate" type="text/html"
    href="http://mosh.nokia.com/search?find=graphic"/>
  <link rel="mobile" type="text/html"
    href="http://mosh.nokia.mobi/search?find=graphic"/>
  <link rel="search" type="application/opensearchdescription xml"
    href="https://mosh-api/atom/1.0/search/description"
    title="Content Search"/>
  <opensearch:totalResults>347</opensearch:totalResults>
  <opensearch:itemsPerPage>12</opensearch:itemsPerPage>
  <opensearch:startIndex>13</opensearch:startIndex>
  <opensearch:Query role="request" searchTerms="graphic"/>
  <generator uri="https://mosh-api/">Nokia MOSH</generator>

  <entry>
    <title>Soccer Game</title>
    <link rel="self"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/content/{GUID}"/>
    <link rel="edit"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/content/{GUID}"/>
    <link rel="comments"
      type="application/atom xml;type=entry"
      href="https://mosh-api/atom/1.0/content/{GUID}/comments"/>
    <link rel="alternate"
      type="text/html"
      href="http://mosh.nokia.com/u/ramsey/c19"/>
    <link rel="mobile"
      type="text/html"
      href="http://mosh.nokia.mobi/u/ramsey/c19"/>
    <id>tag:mosh.nokia.com,2008-01-22:atom/1.0/content/{GUID}</id>
    <published>2008-01-22T17:08:33Z</published>
    <updated>2008-01-22T17:08:33Z</updated>
    <app:edited>2008-01-22T17:08:33Z</app:edited>
    <category
      scheme="https://mosh-api/atom/1.0/categories/types"
      term="2"
      label="game"/>
    <author>
      <name>ramsey</name>
      <uri>https://mosh-api/atom/1.0/users/ramsey</uri>
    </author>
    <summary>
      j2me game
    </summary>
    <content type="application/java-archive"
      src="http://mosh.nokia.com/u/ramsey/c19/downloadFile"/>
    <dcterms:title>Soccer.jar</dcterms:title>
    <dcterms:subject>soccer</dcterms:subject>
    <dcterms:subject>game</dcterms:subject>
    <relevance:score>0.95</relevance:score>
  </entry>

</feed>

Figure 12: Search Results Collection Document

11 Link Relation Extentions

The MOSH API augments the IANA Registry of Link Relations values defined by Sections 4.2.7.2 of [#RFC4287 [RFC4287]] and 11 of [#RFC5023 [RFC5023]]. The MOSH API does not add these values to the Registry of Link Relations, and, thus, these values are known only to MOSH API Clients.

This document defines six link relation values for the MOSH API:

  1. The value "collections" signifies that the URI in the value of the href attribute identifies a Collection Document of user collections for the user represented by the Entry. This value only has context in Entries representing users.
  2. The value "comments" signifies that the URI in the value of the href attribute identifies a Collection Document of comments about the Entry. This value has context for Entries representing users, user collections, and content items.
  3. The value "mobile" signifies that the URI in the value of the href attribute identifies an alternate representation of the current entity for mobile devices, whether it be a Feed or an Entry. This value is valid for all Feeds and Entries that have an "alternate" relation.
  4. The value "people" signifies that the URI in the value of the href attribute identifies a Collection Document of user people for the user represented by the Entry. This value only has context in Entries representing users.
  5. The value "seeks" signifies that the URI in the value of the href attribute identifies a Collection Document of user Seeks for the user represented by the Entry. This value only has context in Entries representing users.
  6. The value "uploads" signifies that the URI in the value of the href attribute identifies a Collection Document of user uploads for the user represented by the Entry. This value only has context in Entries representing users.

12 Use of the Tag URI Scheme for IDs

[#RFC4287 [RFC4287]] specifies that Atom Feeds and Atom Entries MUST have exactly one atom:id element that is globally unique and never changes. Furthermore, wherever the same Entry occurs, whether in a Collection or Entry Document, it MUST maintain the same atom:id value. The MOSH API adheres to [#RFC4151 [RFC4151]] to create IDs using the "tag" URI scheme.

The tag structure for the MOSH API will adhere to the following rules for creation:

  1. All tags begin wi