UserPreferences

PaceProblemStatements


Abstract

Provide surrounding context in early drafts, so new readers of the spec will understand the document better. These sections would not appear in the final document.

Status

Open

Author: RobertSayre

Rationale

In discussions on the Atom protocol, it isn't always evident what problem a given proposal aims to solve.

A recommended strategy for alleviating this problem is given in [WWW]If you are going to write WebDAV Standards - PLEASE READ THIS. The document has nothing to do with WebDAV per se. It focuses on the proposal process.

"One of the smartest things the WebDAV authors ever did was to listen to Larry Masinter's [WWW]suggestions regarding how to put together our early drafts. The way we implemented his suggestion was to require that every feature in the spec have three sections.

Section 1 - A description of the problem the feature was meant to address

Section 2 - A proposed solution for the problem

Section 3 - An explanation of the design rationale behind the solution."

This Pace suggests a similar structure for the protocol draft:

1.) Problem Description

2.) The normative text (aka solution)

3.) Design Rationale

Proposal

The Atom Publishing Protocol Model

1.) Problem Description

What types of resource does the spec define, and what methods are used to act on them?

2.) [current text]

3.) Rationale

The specification should define only the methods and resources required for interoperation.

PostURI

1.) Problem Description

Existing weblog software, and perhaps the weblog model itself, assumes that the server will create new URIs. You supply the content, and the server figures out where to put it. There is typically no "save as" procedure.

2.) [current text]

3.) Rationale

Users will know what their server will do with a new entry. Most public blog resources are "[WWW]dynamic" in the sense that they are derived from other resources. For instance, the index page of a blog is often derived from the N most recent publishing events.

The "Locating" section presents a strategy for locating the static resources that given dynamic resource is derived from.

The Response Code sections present specializations of the response codes' meanings in HTTP.

EditURI

The EditURI is similar to the PostURI, except that it does not create subordinate resources. It identifies resources that were created by the PostURI, and methods for modifying a given resource are defined.

1.) Problem Description

How does a client modify or delete an existing entry?

2.)

3.) Rationale

HTTP PUT and DELETE are close to ideal methods for modification and deletion. HTTP GET on an EditURI provides a "static" or "source" representation.

The rationale for the Location and Response code sections are identical to the PostURI.

FeedURI

1.) Problem Description

How can a the configuration requirements for clients be minimized?

2.) [current text]

3.) Rationale

@@ I don't think anyone is happy with this section @@

Atom Request and Response Body Constraints

1.) Problem Description

Some parts of an Atom entry are controlled by the client, while some are controlled by the server.

2.) [current text]

3.) Rationale

By specifying which elements must be present in a given request or response, and semantics based on their presence or absence, a protocol is implied.

ResourcePostURI

1.) Problem Description

How can a client add non-entry resources for use in Atom entries to a site?

2.) [forthcoming PaceSimpleResourcePosting]

3.) Rationale

A mechanism similar to a PostURI can be used for the creation of resources. Once created, non-entry resources are manipulated using plain HTTP.

Templates

1.) Problem Description

How can a client program discover, add, manipulate, and delete templates in a format that a given server implementation supports. How can a client discover what format the server expects templates to conform to?

Categories

1.) Problem Description

Many, if not most, episodic website server software allows grouping of entries by "categories" with user-defined semantics. How can the Atom protocol allow clients to manipulate an entry's membership in one or more categories?

Access Control

1.) Problem Description

How can a client discover and manipulate access privileges for a given entry? What credentials are required? The most common instance of this capability would appear to be "draft" entries--entries which are visible to authenticated users in their source form but not in any derived resources.

User Management

1.) Problem Description

Most blogs or journals have one "admin" user who grants privileges to zero or more users with some subset of the "admin" user's privileges. The "admin" user needs a way to create, modify, and delete the privileges of those users.

Impacts

Notes


CategoryProposals