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 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 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 "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.