Atom Publishing Protocol – Introduction

Developers > Protocol


What is Atom?

Atom is the name of an XML-based Web content and metadata syndication format, and an application-level protocol for publishing and editing Web resources.

The Atom Publishing Protocol is an application-level protocol for publishing and editing Web Resources using HTTP and XML.

About this document

This document focuses on The Atom Publishing Protocol produced by the IETF AtomPub Working Group. In the event that this document differs from the RFC, the RFC is to be considered authoritative.

General considerations:

  • The Terms that are used in this introduction are defined in the Terminology section of the Atom Publishing Protocol specification
  • All atom:* elements described in this document must be in the namespace.
  • All app:* elements described in this document must be in the namespace.
  • xml:lang may be used to identify the language of any human readable text.
  • xml:base may be used to control how relative URIs are resolved.
  • Servers can choose to accept, reject, delay, moderate, censor, reformat, translate, relocate, or re-categorize the content submitted to them. Only some of these choices are immediately relayed back to the client in responses to client requests. As a result, client software needs to be flexible and accept whatever the server decides to provide as responses.
  • Implementers are advised to pay attention to cache controls and to make use of the mechanisms available in HTTP when editing Resources.
  • Foreign markup can be used anywhere within a Category or Service Document, or within an app:control element.

Service Documents

Applicable HTTP methods: GET.

Service Documents enable the discovery of the capabilities and locations of Collections: (example).

Service Documents are identified with the application/atomsvc+xml media type.

The app:service Element

An app:service element contains one or more Workspaces.

The app:workspace Element

An app:workspace element contains an atom:title element which provides a human-readable title for the Workspace. An app:workspace element can also contain any number of Collections.

The app:collection Element

When present in an app:workspace, an app:collection element describes a Collection of Resources available for editing. When present in an atom:feed or atom:source element in an Atom Feed Document, it identifies a Collection by which new Entries can be added to appear in the feed.

The app:collection element has one required attribute, href, whose value gives the IRI of the Collection.

An app:collection contains one atom:title element which provides a human-readable title for the Collection. An app:collection element may also contain any number of app:accept and app:collection elements.

The app:accept Element

The value of an app:accept element is a media range as defined by HTTP and specifies a type of representation that can be POSTed to a Collection. A value of application/atom+xml;type=entry indicates that Atom Entry Documents can be POSTed to the Collection.

If no app:accept element is present, only Atom Entry Documents can be POSTed to the Collection. If only one app:accept element exists and it is empty, the Collection does not support the creation of new Entries.

The app:categories Element

An app:categories element may contain an href attribute, whose value is the location of a Category Document. Alternately, an app:categories element can be included inline in a Service Document. When included inline, it has the same format and meaning as an app:categories element in a separate Categories Document.

Category Documents

Applicable HTTP methods: GET.

Category Documents indicate the categories allowed in a Collection: (example).

Category Documents are identified with the application/atomcat+xml media type.

The app:categories Element

An app:categories element can contain any number of atom:category elements.

An atom:category child element that has no “scheme” attribute inherits the attribute from its app:categories parent.

An app:categories element can contain a “fixed” attribute, with a value of either yes or no, indicating whether the server accepts POSTs of Entry Resources which contain categories not in this list. The default for this attribute is no.

Collection Documents

Applicable HTTP methods: GET and POST.

A Collection is represented by an Atom Feed Document.

Feed Documents may contain a partial list of the Collection’s members, and a link to the next partial list feed. The first such partial list returned will contain the most recently edited member Resources and an atom:link with a next relation whose href value is the URI of the next partial list of the Collection. This next partial list will contain the next most recently edited set of Member Resources, and so on. In addition to the next relation, partial list feeds may contain link elements with rel attribute values of previous, first, and last, that can be used to navigate through the complete set of entries in the Collection.

Entries in a Collection Document should be ordered by their app:edited property, with the most recently edited Entries coming first in the document order.

A Resource whose IRI is listed in a Collection is called a Member Resource. The protocol defines two kinds of Member Resources — Entry Resources and Media Resources. A Media Resource is described within a Collection using an Entry called a Media Link Entry.

Entries in a collection contain atom:link elements with a link relation of edit, and some subset of metadata information about the entry itself. As the Atom Entry in the Collection Feed need not always be a full representation of an Entry Resource, clients should perform a GET on the URI of the Member Entry before editing it.

Media Link Entries in a collection contain an additional atom:link elements with a link relation of edit-media. If Media Link Entries contain multiple link relations with a value of edit-media, these links must all differ in the values that they provide for type and/or hreflang attributes.

The POST Method

POST is used to create a new, dynamically named, Member Resource. When the client submits non-Atom-Entry representations to a Collection for creation, two Resources are always created — a Media Entry for the requested Resource, and a Media Link Entry for metadata about the Resource that will appear in the Collection.

The server can signal the media types it will accept using the app:accept element in the Service Document.

Successful member creation is indicated with a 201 (Created) response code. When the Collection responds with a status code of 201, it should also return a response body which contains an Atom Entry Document representing the newly created Resource. Since the server is free to alter the POSTed Entry, for example, by changing the content of the atom:id element, returning the Entry can be useful to the client, enabling it to correlate the client and server views of the new Entry.

When a Member Resource is created, its Member Entry URI is returned in a Location header in the Collection’s response.

If the creation request contained an Atom Entry Document, the client can assume that the response entity is a complete representation of the newly created Entry only if the response from the server also contains a Content-Location header that matches the Location header.

The Slug Header

Slug is an HTTP entity-header whose presence in a POST to a Collection constitutes a request by the client to use the header’s value as part of any URIs that would normally be used to retrieve the to-be-created Entry or Media Resources.

Servers may use, alter, or ignore the value of the Slug header when creating the Member URI of the newly created Resource, for instance, by using some or all of the words in the value for the last URI segment. Servers may also use the value when creating the atom:id, or as the title of a Media Link Entry.

Entry Resources

Applicable HTTP methods: GET, PUT, and DELETE.

Entry Resources are represented as Atom Entry Documents.

A Member Entry should contain an atom:link element with a link relation of edit, which indicates the Member URI.

The app:edited Element

The app:edited element is a Date construct whose content indicates the last time an Entry was edited. If the entry has not been edited yet, the content indicates the time it was created.

The app:control Element

The app:control element can contain an app:draft element as defined below.

The app:draft Element

If the value is no, this indicates a client request that the Member Resource be made publicly visible. If the app:draft element is not present, the default value is no.

Media Resources

Applicable HTTP methods: GET, PUT, and DELETE.

Media Resources can have representations in any media type.

Media Link Entries

Applicable HTTP methods: GET, PUT, and DELETE.

A Media Link Entry is represented as an Atom Entry and contains the metadata and IRI of the (perhaps non-textual) Media Resource. The Media Link Entry thus makes the metadata about the Media Resource separately available for retrieval and alteration.

Successful responses to creation requests will include the URI of the Media Link Entry in the Location header. The Media Link Entry should contain an atom:link element with a link relation of edit-media that contains the Media Resource IRI. The Media Link Entry will also have an atom:content element with a src attribute. The value of the src attribute is an IRI for the newly created Media Resource. The IRI of the src attribute on the atom:content element need not be the same as the Media Resource IRI. For example, the src attribute value might instead be a link into a static cache or content distribution network and not the Media Resource IRI.

Note that Atom Entries must contain an atom:summary element. Thus, upon successful creation of a Media Link Entry, a server may choose to populate the atom:summary element (as well as any other mandatory elements such as atom:id, atom:author, and atom:title) with content derived from the POSTed entity or from any other source. A server might not allow a client to modify the server-selected values for these elements.