UserPreferences

PaceNonEntryResources


Abstract

This proposal extends the Atom API to allow for creation and management of non-entry resources, such as media (images, audio, video), site support files (stylesheets, templates, configuration), and static resources (documents, downloads). A new URI endpoint is proposed, ResourcePostURI, for creating resources with locations assigned by the server. Multiple resource locations are allowed.

PaceSimpleContentType proposes two alternatives for making a non-entry resource the published content of an entry, using either <content src="URI"> or <link rel="content" href="URI">.

Status

Open -- incomplete

PaceSimpleResourcePosting is an alternative proposal that can potentially merge with this proposal.

To better align this Pace with PaceSimpleResourcePosting, the ResourceBaseURI for using PUT-to-create was separated out to PacePutToCreate, and the proposal for reorganizing the protocol draft will also be moved to a separate Pace.

PaceResource is an alternative that provides a <resource> element in place of the <entry> element, and uses base64 for binary resources. Resources are managed using the same methods and URI locations as used for <entry>s.

The PaceObjectModule and PaceDontSyndicate were alternative proposals that have been closed.

Rationale

This proposal removes the constraint of using an XML wrapper for acting on arbitrary, non-entry web resources and recognizes that resources on the web can be acted upon directly. It provides a mechanism for an Atom server to communicate to an Atom client URI locations for creating non-entry resources on the server, using POST, and for editing those resources with PUT, GET, and DELETE.

The following is copied from PaceDontSyndicate:

The [WWW]Atom Syndication Format 0.3 pre-draft provides for the atom:content element to have @type="multipart/alternative", creating a simple two-level hierarchy. No existing syndication format offers such a content hierarchy. The use-case for this is said to be multimedia entries which include non-textual objects (e.g. pictures or video).

This notion of a compound entry accords not only adds complexity to the Atom format and protocol, it accords poorly with [WWW]Web Architecture; on the Web, everything either has a URI and is a Resource, or it doesn't exist. While there is the possibility of alternative representations of a resource via content-negotiation, it is fairly poorly supported and fails to meet many real needs. Put simply, the Web doesn't know about compound objects.

A common pattern in online publications for which feeds will be generated is for HTML-encoded narrative to embed pointers to graphics or other multimedia objects. The HTML and the other objects are all first-class Web resources, but normally only one of them (usually the HTML) will have its URI published to the world.

Proposal

In the protocol document, add to 4.2 Terminology:

In 4.3 The AtomAPI Model, delete "There are three major classes of URIs in this specification: PostURI, FeedURI and EditURI." and add the following to the summary list of URIs:

In section 5.4.1 Link Tag @rel, add:

In section 5.4.1 Link Tag @rel, clarify that the resource is an entry, "... is used to create new entry resources."

As originally written in this Pace, it is recommended that the access patterns (how to use POST, PUT, GET, DELETE in a generic fashion) should be separated from the descriptions of the specific URIs. That refactoring will go in a different Pace. Depending on the status of that Pace, this Pace is incomplete until spec text is added either in the current style or the style of the other pace.

The section describing ResourcePostURI will note:

Impacts

ResourceEditURI conflicts with API section 7.1 SOAP Enabling. The second alternate proposal in PacePutDelete's, Atom-Action header, would work.

ResourcePostURI technically does not conflict with 7.1 SOAP Enabling because a "fallback" is not necessary for POST, but someone who is "thinking in SOAP" might not realize that an XML wrapper isn't being used or allowed here.

Notes


CategoryProposals