Henry, I very much do NOT want the Introspection Wars to start over again, however, if folks can behave, I think there are some good things we can do at this point.
Over the past nine months I've written five Atom server implementations and am currently working with Elias on a sixth. In every case, the introspection document played a non-critical role as far as the core behavior of the protocol is concerned. They have, however, proved useful for bootstrap when augmented with information about what media types, features, extensions, behaviors, etc are supported by an implementation, or when trying to figure out the complete set of collections that are available to a client. To be completely honest, at this point, I would very much prefer that the service document format be dropped from the spec and that the app:collection element be redefined as an extension to atom:feed, atom:source and atom:entry. This would allow feeds/entries to claim an association with an APP endpoint and gives a place to hang APP specific extension metadata. A service document format that incorporates app:collection could be reasonably defined by a separate specification. That said, however, I'm not going to argue the point because the stuff that's currently in the spec is very simple and low cost to implement, serves a useful purpose, and does not get in the way of implementing the core protocol operations. - James Henry Story wrote: > > This pace is a simplification pace and is under development. Feedback on > the general idea would be appreciated, as well as on positive > improovements to it. > > Henry > > http://www.intertwingly.net/wiki/pie/PaceNoServiceDocument > > > #pragma section-numbers off > > == Abstract == > > Remove the Service Document from the Protocol Spec. > > == Status == > > under development > > == Rationale == > > The Service document is not well enough defined, and does not contain > any information that is really needed for the protocol. > It can be removed safely from the protocol document. > > == Proposal == > > Replace 5.1 > > {{{ > 5.1 Retrieving an Introspection Document > > Client Server > | | > | 1.) GET to URI of Introspection Document | > |------------------------------------------>| > | | > | 2.) Introspection Document | > |<------------------------------------------| > | | > > 1. The client sends a GET request to the URI of the Introspection > Document. > > 2. The server responds with the document enumerating the IRIs of a > set of Collections and the capabilities of those Collections > supported by the server. The content of this document can vary > based on aspects of the client request, including, but not > limited to, authentication credentials. > }}} > > to > > {{{ > 5.1 Retrieving a Collection > > Client Server > | | > | 1.) GET to URI of Collection | > |------------------------------------------>| > | | > | 2.) Feed Document | > |<------------------------------------------| > | | > > 1. The client sends a GET request to the Collection URI > > 2. The server responds with an atom Feed document . If this document > contains an > app:accept element, this specifies what type of mime types can be > POSTED to this uri. > > }}} > > > > Remove section 7. Introspection Documents > > and replace with > > {{{ > 7. Introspection extensions > > The "app:accept" Element > > The atom:feed element MAY contain one "app:accept" element. The > app:accept element value specifies a comma-separated list of media- > ranges [RFC2616] identifying the types of representations that can be > POSTed to the Collection's URI. Whitespace separating the media- > range values is considered insignificant and MUST be ignored. > > The app:accept element is similar to the HTTP Accept request-header > [RFC2616] with the exception that app:accept has no notion of > preference. Accordingly, the value syntax of app:accept does not use > accept-params or "q" parameters as specified in [RFC2616], section > 14.1. The order of media-ranges is not significant. The following > lists are all equivalent: > > > <app:accept>image/png, image/*</app:accept> > <app:accept>image/*, image/png</app:accept> > <app:accept>image/*</app:accept> > > A value of "entry" indicates that Atom Entry Documents can be posted > to the Collection. If the accept element is omitted, or empty, > clients SHOULD assume that only Atom Entry documents will be accepted > by the collection. > > > appAccept = > element app:accept { > appCommonAttributes, > ( appTypeValue? ) > } > > appTypeValue = ( "entry" | media-type |entry-or-media-type ) > media-type = xsd:string { pattern = "entry,(.+/.+,?)*" } > entry-or-media-type = xsd:string { pattern = "(.+/.+,?)*" } > > }}} > > Remove most of appendix B. relating to service documents. > > > == Impacts == > > Positive. > It mostly just removes information from the spec, so it cannot go wrong. > Since the spec will be shorter, it will be easier to show it to be > correct, and so it will pass through the standardisation process faster. > > == Notes == > > > ---- > > CategoryProposals > >
