Atom documents

Atom documents are one of the following types: entry documents, feed documents, collections, service documents, or category documents.

Atom entry documents

An Atom entry document is an XML document that contains a single item of information, known as an entry, for the Atom feed.

An Atom entry document consists of an <atom:entry> element that contains a number of child elements. The child elements provide the content for the entry and also metadata about the entry, such as its title or the time when it was first published.

The content of an Atom entry can be plain text, HTML, XHTML, or another IANA (Internet Assigned Numbers Authority) media type. IANA media types are listed at http://www.iana.org/assignments/media-types/media-types.xhtml. An Atom entry can also have as its content a link to a media resource such as a movie or image, in which case it is called a media link entry.

The media type for an Atom entry document is application/atom+xml.

Atom feed documents

An Atom feed document is an XML document that provides metadata about an Atom feed and one or more entries for the feed. When a client makes a request for information from the feed, the server generates a feed document that includes a suitable number of Atom entries to fulfil the request.

An Atom feed document consists of an <atom:feed> element that contains a number of child elements. The <atom:entry> element is the most important child element, but normally the entries for the feed exist as separate XML documents, and the server adds them when it serves the feed document. An Atom feed document is still an acceptable document when it does not contain any <atom:entry> elements.

The other child elements contain metadata about the feed, such as its title and subtitle, or its main author. Some of the items of metadata in the Atom feed document, such as the author's details and the information about intellectual property rights, can apply to all the entries in the feed unless an entry includes its own version of that item of metadata.

The media type for an Atom feed document is application/atom+xml.

Atom collection

An Atom collection is a special kind of Atom feed document that lists the URLs of Atom entries that are available to be edited. Its format is like that of an ordinary Atom feed document with the addition of some specialized elements. It is distinguished as a collection by being listed in an Atom service document.

An Atom collection contains some specialized <atom:link> elements. If the collection is large enough that more than one feed document is required to return all the entries, the elements <atom:link rel="first">, <atom:link rel="last">, <atom:link rel="next">, and <atom:link rel="previous"> supply navigation between the feed documents. Entries also have an <atom:link rel="edit"> link to which edit requests can be directed. The <app:edited> element is added to entries in a collection to state the time of the last edit for each entry.

When Atom entries are made available as a collection, a client can edit or delete the existing entries and create new entries for the collection. The client manipulates the entries by sending HTTP requests to the server as follows:

GET

Retrieve a single Atom entry or a list of Atom entries. GET requests for a list of Atom entries are sent to the URL of the collection, as stated in the Atom service document. GET requests for a single Atom entry are sent to the URL of an individual Atom entry in the collection, as stated in the <atom:link rel="edit"> link for the entry.

POST

Create a new Atom entry. POST requests are sent to the URL of the collection.

PUT

Edit an existing Atom entry that the client has obtained using a GET request. PUT requests are sent to the URL of an individual Atom entry in the collection.

DELETE

Delete an existing Atom entry. DELETE requests are sent to the URL of an individual Atom entry in the collection.

The server sends an appropriate HTTP response to the client in each case. A server can change the metadata that the client provides for the entry, so when a client makes a successful POST or PUT request, the server also returns a copy of the new entry as the body of the response.

As well as containing standard Atom entries, a collection can also contain media resources, such as a movie or image. If a server supports media resources, it creates special Atom entries known as media link entries in the collection to provide links to these resources. CICS does not provide support for media resources.

Atom service document

An Atom service document is an XML document that lists the collections that are available from a server.

An Atom service document has the root element <app:service>. (The app: prefix is the namespace prefix for the Atom Publishing Protocol.) It has one or more <app:workspace> elements that define workspaces containing a number of <app:collection> elements. A workspace is used only for grouping collections; you cannot perform any actions on a workspace.

The <app:collection> elements list the URL and title of each collection, and might also state the types of input that the collection accepts and the categories that can be used for entries.

The media type for an Atom service document is application/atomsvc+xml.

Atom category document

A category document contains lists of categories for the entries in a collection. Categories can also be specified in a service document. Separate category documents are useful if you want to use the same categories to define multiple Atom feeds.

An Atom category document has the root element <app:categories>. (The app: prefix is the namespace prefix for the Atom Publishing Protocol.) The <app:categories> element contains a list of <atom:category> elements that are permitted for entries in a collection. The list of categories can be fixed, in which case the server can reject entries with other categories, or it can be open, so that other categories can be used.

If a separate Atom category document is used in the place of a list of categories in an Atom service document, the category document is referenced in the service document by its URL.

The media type for an Atom collection is application/atomcat+xml.