PaceCollectionIdiom

[Joe Gregorio <joe.gregorio@xxxxxxxxx>]

http://intertwingly.net/wiki/pie/PaceCollectionIdiom

Based on the feedback I have named this the Collection Management
Idiom as opposed to the  List Management Idiom.


--------------------------------------

== Abstract ==

A recurring pattern of behaviour is seem among several of the protocol
facets. To highlight this pattern and to make the spec easier to read
the pattern should be called out early in the document and then
referred to later as appropriate.

== Status ==

Open

Author: JoeGregorio


== Rationale ==

Highlighting a common idiom will make the protocol easier to understand.

== Proposal ==

Add the following text to section 2, note that this is following the
form outlined in PaceProblemStatements.



2.1 The Collection Management Idiom

2.1.1 Problem

Several facets of the Atom Publishing Protocol have similar methods of
interaction. Currently such patterns are not called out and this could
end up making the text repetitive.

2.1.2 Normative Text

Several facets of the Atom Publishing Protocol fall into the same
pattern of behavior. These common interaction patterns are called
idioms, and the most common idiom is "Collection Management".

In this idiom we are managing a collection of resources that have the
following properties:

 1. Each resource in the collection has it's own URI. This is called
the Collection Item, there is the Collection Item URI which points to
the Collection Item Resource. Each resource supports GET, PUT and
DELETE for updating the resource.
 1. There is a top level resource that represent the collection of
those resources. This is called the Collection Resource and the URI
for the top level resource of a collection is the Collection URI.
GETting that resource returns a representation that enumerates some or
all of the resources in the collection. POSTing an appropriate
representation to this top level resource will create a new resource
in the collection with that representation.

What we have here is a set, with the ability to add and remove
elements from the set and the ability to inspect and update elements
that are already in the set.

Note that the resouces in the collection might not have the same
representations.

2.1.3 Design Rationale

Pointing out those patterns early, giving them names, and outlining
the constraints will make latter parts of the spec easier to follow
(and hopefully easier to write). For example, we could start by saying
that managing users follows the Collection Management Idiom where
UsersURI is the Collection Item URI and UserManagementURI is the
Collection Item URI. It also useful for pointing out differences, for
example PaceSimpleResourcePosting follows the Collection Management
idiom but it doesn't have a Collection URI. Of course, writing that
may make you question why it doesn't have one, which is a good thing.


== Impacts ==



== Notes ==


----

CategoryProposals