| draft-ietf-atompub-protocol-02.txt | draft-ietf-atompub-protocol-03.txt | |||
|---|---|---|---|---|
| Network Working Group J. Gregorio, Ed. | Network Working Group J. Gregorio, Ed. | |||
| Internet-Draft BitWorking, Inc | Internet-Draft BitWorking, Inc | |||
| Expires: March 22, 2005 R. Sayre, Ed. | Expires: September 19, 2005 R. Sayre, Ed. | |||
| Boswijck Memex Consulting | Boswijck Memex Consulting | |||
| September 21, 2004 | March 18, 2005 | |||
| The Atom Publishing Protocol | The Atom Publishing Protocol | |||
| draft-ietf-atompub-protocol-02.txt | draft-ietf-atompub-protocol-03.txt | |||
| Status of this Memo | Status of this Memo | |||
| By submitting this Internet-Draft, I certify that any applicable | This document is an Internet-Draft and is subject to all provisions | |||
| patent or other IPR claims of which I am aware have been disclosed, | of Section 3 of RFC 3667. By submitting this Internet-Draft, each | |||
| and any of which I become aware will be disclosed, in accordance with | author represents that any applicable patent or other IPR claims of | |||
| which he or she is aware have been or will be disclosed, and any of | ||||
| which he or she become aware will be disclosed, in accordance with | ||||
| RFC 3668. | RFC 3668. | |||
| Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
| Task Force (IETF), its areas, and its working groups. Note that | Task Force (IETF), its areas, and its working groups. Note that | |||
| other groups may also distribute working documents as | other groups may also distribute working documents as | |||
| Internet-Drafts. | Internet-Drafts. | |||
| Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
| and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
| time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
| material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
| The list of current Internet-Drafts can be accessed at | The list of current Internet-Drafts can be accessed at | |||
| http://www.ietf.org/ietf/1id-abstracts.txt. | http://www.ietf.org/ietf/1id-abstracts.txt. | |||
| The list of Internet-Draft Shadow Directories can be accessed at | The list of Internet-Draft Shadow Directories can be accessed at | |||
| http://www.ietf.org/shadow.html. | http://www.ietf.org/shadow.html. | |||
| This Internet-Draft will expire on March 22, 2005. | This Internet-Draft will expire on September 19, 2005. | |||
| Copyright Notice | Copyright Notice | |||
| Copyright (C) The Internet Society (2004). All Rights Reserved. | Copyright (C) The Internet Society (2005). | |||
| Abstract | Abstract | |||
| This memo presents a protocol for using XML (Extensible Markup | This memo presents a protocol for using XML (Extensible Markup | |||
| Language) and HTTP (HyperText Transport Protocol) to edit content. | Language) and HTTP (HyperText Transport Protocol) to edit content. | |||
| The Atom Publishing Protocol is an application-level protocol for | The Atom Publishing Protocol is an application-level protocol for | |||
| publishing and editing Web resources belonging to periodically | publishing and editing Web resources belonging to periodically | |||
| updated websites. The protocol at its core is the HTTP transport of | updated websites. The protocol at its core is the HTTP transport of | |||
| Atom-formatted representations. The Atom format is documented in the | Atom-formatted representations. The Atom format is documented in the | |||
| Atom Syndication Format (draft-ietf-atompub-format-02.txt). | Atom Syndication Format (draft-ietf-atompub-format-06.txt). | |||
| Editorial Note | Editorial Note | |||
| To provide feedback on this Internet-Draft, join the | To provide feedback on this Internet-Draft, join the atom-syntax | |||
| <http://www.imc.org/atom-syntax/index.html>. | mailing list (http://www.imc.org/atom-syntax/index.html) [1]. | |||
| Table of Contents | Table of Contents | |||
| 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
| 1.1 Notational Conventions . . . . . . . . . . . . . . . . . . 4 | 1.1 Notational Conventions . . . . . . . . . . . . . . . . . . 4 | |||
| 1.2 Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 | 1.2 Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
| 2. The Atom Publishing Protocol Model . . . . . . . . . . . . . 4 | 2. The Atom Publishing Protocol Model . . . . . . . . . . . . . 4 | |||
| 2.1 Atom Collections . . . . . . . . . . . . . . . . . . . . . 4 | ||||
| 2.1.1 Usage . . . . . . . . . . . . . . . . . . . . . . . . 5 | ||||
| 2.1.2 Client and Server Interaction . . . . . . . . . . . . 5 | ||||
| 3. Functional Specification . . . . . . . . . . . . . . . . . . 5 | 3. Functional Specification . . . . . . . . . . . . . . . . . . 5 | |||
| 3.1 PostURI . . . . . . . . . . . . . . . . . . . . . . . . . 5 | 3.1 Collections . . . . . . . . . . . . . . . . . . . . . . . 6 | |||
| 3.1.1 Locating the PostURI . . . . . . . . . . . . . . . . . 5 | 3.1.1 Collection Document . . . . . . . . . . . . . . . . . 6 | |||
| 3.1.2 Request . . . . . . . . . . . . . . . . . . . . . . . 5 | 3.1.2 Elements in a Collection Document . . . . . . . . . . 6 | |||
| 3.1.3 Response . . . . . . . . . . . . . . . . . . . . . . . 5 | 3.1.3 Collection Requests . . . . . . . . . . . . . . . . . 7 | |||
| 3.2 EditURI . . . . . . . . . . . . . . . . . . . . . . . . . 7 | 3.2 Introspection . . . . . . . . . . . . . . . . . . . . . . 8 | |||
| 3.2.1 Locating . . . . . . . . . . . . . . . . . . . . . . . 7 | 3.2.1 Service Document . . . . . . . . . . . . . . . . . . . 8 | |||
| 3.2.2 Request . . . . . . . . . . . . . . . . . . . . . . . 7 | 3.3 Entry Collection . . . . . . . . . . . . . . . . . . . . . 9 | |||
| 3.3 FeedURI . . . . . . . . . . . . . . . . . . . . . . . . . 9 | ||||
| 3.3.1 Locating . . . . . . . . . . . . . . . . . . . . . . . 10 | 3.3.1 Locating . . . . . . . . . . . . . . . . . . . . . . . 10 | |||
| 3.3.2 Request . . . . . . . . . . . . . . . . . . . . . . . 10 | 3.4 Simple Resource Collection . . . . . . . . . . . . . . . . 10 | |||
| 3.3.3 Response . . . . . . . . . . . . . . . . . . . . . . . 10 | ||||
| 3.4 ResourcePostURI . . . . . . . . . . . . . . . . . . . . . 10 | ||||
| 3.4.1 Locating . . . . . . . . . . . . . . . . . . . . . . . 10 | 3.4.1 Locating . . . . . . . . . . . . . . . . . . . . . . . 10 | |||
| 3.4.2 Request . . . . . . . . . . . . . . . . . . . . . . . 11 | 3.4.2 Request . . . . . . . . . . . . . . . . . . . . . . . 10 | |||
| 3.4.3 Response . . . . . . . . . . . . . . . . . . . . . . . 11 | 3.5 Atom Request and Response Body Constraints . . . . . . . . 11 | |||
| 3.5 Link Tag . . . . . . . . . . . . . . . . . . . . . . . . . 12 | 3.5.1 id . . . . . . . . . . . . . . . . . . . . . . . . . . 11 | |||
| 3.5.1 rel . . . . . . . . . . . . . . . . . . . . . . . . . 12 | 3.5.2 link . . . . . . . . . . . . . . . . . . . . . . . . . 11 | |||
| 3.5.2 href . . . . . . . . . . . . . . . . . . . . . . . . . 12 | 3.5.3 title . . . . . . . . . . . . . . . . . . . . . . . . 11 | |||
| 3.5.3 title . . . . . . . . . . . . . . . . . . . . . . . . 13 | 3.5.4 summary . . . . . . . . . . . . . . . . . . . . . . . 11 | |||
| 3.5.4 type . . . . . . . . . . . . . . . . . . . . . . . . . 13 | 3.5.5 content . . . . . . . . . . . . . . . . . . . . . . . 12 | |||
| 3.6 Atom Request and Response Body Constraints . . . . . . . . 13 | 3.5.6 issued . . . . . . . . . . . . . . . . . . . . . . . . 12 | |||
| 3.6.1 id . . . . . . . . . . . . . . . . . . . . . . . . . . 13 | 3.5.7 modified . . . . . . . . . . . . . . . . . . . . . . . 12 | |||
| 3.6.2 link . . . . . . . . . . . . . . . . . . . . . . . . . 13 | 3.5.8 created . . . . . . . . . . . . . . . . . . . . . . . 12 | |||
| 3.6.3 title . . . . . . . . . . . . . . . . . . . . . . . . 13 | 3.5.9 author . . . . . . . . . . . . . . . . . . . . . . . . 13 | |||
| 3.6.4 summary . . . . . . . . . . . . . . . . . . . . . . . 14 | 3.5.10 contributor . . . . . . . . . . . . . . . . . . . . 13 | |||
| 3.6.5 content . . . . . . . . . . . . . . . . . . . . . . . 14 | 3.5.11 generator . . . . . . . . . . . . . . . . . . . . . 13 | |||
| 3.6.6 issued . . . . . . . . . . . . . . . . . . . . . . . . 14 | 3.6 Securing the Atom Protocol . . . . . . . . . . . . . . . . 13 | |||
| 3.6.7 modified . . . . . . . . . . . . . . . . . . . . . . . 15 | 3.6.1 [@@TBD@@ CGI Authentication] . . . . . . . . . . . . . 14 | |||
| 3.6.8 created . . . . . . . . . . . . . . . . . . . . . . . 15 | 4. Security Considerations . . . . . . . . . . . . . . . . . . 14 | |||
| 3.6.9 author . . . . . . . . . . . . . . . . . . . . . . . . 15 | 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 14 | |||
| 3.6.10 contributor . . . . . . . . . . . . . . . . . . . . 15 | 6. Appendix A - SOAP Enabling . . . . . . . . . . . . . . . . . 15 | |||
| 3.6.11 generator . . . . . . . . . . . . . . . . . . . . . 15 | 6.1 Servers . . . . . . . . . . . . . . . . . . . . . . . . . 15 | |||
| 3.7 Securing the Atom Protocol . . . . . . . . . . . . . . . . 16 | 6.2 Clients . . . . . . . . . . . . . . . . . . . . . . . . . 15 | |||
| 3.7.1 [@@TBD@@ CGI Authentication] . . . . . . . . . . . . . 16 | 7. Appendix B - Examples . . . . . . . . . . . . . . . . . . . 15 | |||
| 4. Security Considerations . . . . . . . . . . . . . . . . . . 16 | 7.1 Example for a weblog . . . . . . . . . . . . . . . . . . . 15 | |||
| 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 17 | 7.2 Example for a wiki . . . . . . . . . . . . . . . . . . . . 15 | |||
| 6. Appendix A - SOAP Enabling . . . . . . . . . . . . . . . . . 17 | 8. Revision History . . . . . . . . . . . . . . . . . . . . . . 15 | |||
| 6.1 Servers . . . . . . . . . . . . . . . . . . . . . . . . . 17 | 9. Normative References . . . . . . . . . . . . . . . . . . . . 17 | |||
| 6.2 Clients . . . . . . . . . . . . . . . . . . . . . . . . . 17 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 18 | |||
| 7. Appendix B - Examples . . . . . . . . . . . . . . . . . . . 17 | Intellectual Property and Copyright Statements . . . . . . . 19 | |||
| 7.1 Example for a weblog . . . . . . . . . . . . . . . . . . . 17 | ||||
| 7.2 Example for a wiki . . . . . . . . . . . . . . . . . . . . 18 | ||||
| 8. Revision History . . . . . . . . . . . . . . . . . . . . . . 18 | ||||
| 9. Normative References . . . . . . . . . . . . . . . . . . . . 19 | ||||
| Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 20 | ||||
| Intellectual Property and Copyright Statements . . . . . . . 21 | ||||
| 1. Introduction | 1. Introduction | |||
| The Atom Publishing Protocol is an application-level protocol for | The Atom Publishing Protocol is an application-level protocol for | |||
| publishing and editing Web resources using HTTP [RFC2616] and XML. | publishing and editing Web resources using HTTP [RFC2616] and XML. | |||
| 1.1 Notational Conventions | 1.1 Notational Conventions | |||
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
| "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | |||
| document are to be interpreted as described in [RFC2119]. | document are to be interpreted as described in [RFC2119]. | |||
| 1.2 Terminology | 1.2 Terminology | |||
| Atom Entry: An Atom Entry is a fragment of a full Atom feed. In this | Atom Entry: An Atom Entry is a fragment of a full Atom feed. In this | |||
| case, the fragment is a single 'entry' element and all its child | case, the fragment is a single 'entry' element and all its child | |||
| elements. Each Atom Entry describes a single Web resource, | elements. Each Atom Entry describes a single Web resource, | |||
| providing metadata and optionally a textual representation of that | providing metadata and optionally a textual representation of that | |||
| resource. | resource. | |||
| PostURI: A URI that is used to create new resources. POSTing an Atom | ||||
| Entry to this URI will create a new resource. | ||||
| EditURI: A URI that is used to edit a resource. The editing is done | ||||
| using the HTTP verbs GET, PUT and DELETE. The representation of | ||||
| the resource is always that of an Atom Entry. | ||||
| FeedURI: The URI which identifies an Atom Feed. | ||||
| 2. The Atom Publishing Protocol Model | 2. The Atom Publishing Protocol Model | |||
| The Atom Publishing Protocol is an application-level protocol for | The Atom Publishing Protocol is an application-level protocol for | |||
| publishing and editing Web resources. Using the common HTTP verbs | publishing and editing Web resources. The primary way of interaction | |||
| provides a pattern for working with all such Web resources: | in the Atom Publishing Protocol is by managing collection of | |||
| resources. All collections support the same basic methods of | ||||
| interaction. In addition, the resources belonging to collections | ||||
| also share the same interaction patterns. Using the common HTTP | ||||
| verbs provides a pattern for working with all such Web resources: | ||||
| o GET is used to retrieve a representation of a resource or perform | o GET is used to retrieve a representation of a resource or perform | |||
| a read-only query. | a read-only query. | |||
| o PUT is used to update a known resource. | o PUT is used to update a known resource. | |||
| o POST is used to create a new dynamically-named resource. | o POST is used to create a new dynamically-named resource. | |||
| o DELETE is used to remove a resource. | o DELETE is used to remove a resource. | |||
| There are four major classes of URI [RFC2396] in this specification: | 2.1 Atom Collections | |||
| PostURI, ResourcePostURI, FeedURI, and EditURI. This specification | ||||
| defines the expected actions for each of the methods listed. A URI | ||||
| MAY support methods not listed here. For example, an EditURI could | ||||
| support a POST or OPTIONS method. However, what those methods do is | ||||
| beyond the scope of this specification. | ||||
| o EditURI: PUT, GET, DELETE | ||||
| o PostURI: POST | ||||
| o FeedURI: GET | ||||
| o ResourcePostURI: POST | ||||
| This document does not specify the form of the URIs that are used. | An Atom collection is a set of items all of the same type ("members" | |||
| of the collection), where the "type" may be, for example: Atom entry, | ||||
| category, template, "simple resource", or any other classification of | ||||
| web resource. | ||||
| Each collection has a URI which is given in the introspection file. | ||||
| A GET on the collection URI MUST produce a collection document as | ||||
| defined in "3.X.1 Collection Document." That document describes PART | ||||
| OF the state of the collection. | ||||
| All the members of a collection have an "updated" property, and the | ||||
| collection is considered to be ordered by this property. A single | ||||
| collection document may not contain all of the members of a | ||||
| collection. If a collection document is the response of a | ||||
| non-partial GET request, and does not contain all of the members of a | ||||
| collection, then it will contain the URI of the next collection | ||||
| document which will contain more of the collection members. By | ||||
| traversing this list of collection documents a client can obtain all | ||||
| of the members of a collection. The 'next' attribute will not be | ||||
| present in the response to a partial GET request. | ||||
| 2.1.1 Usage | ||||
| Below two usages are outlined for Atom Collections. They are here to | ||||
| highlight common idioms for interacting with a Collection Resource | ||||
| and not a normative interaction pattern. | ||||
| The Atom Collection can be used by clients in two ways. In the first | ||||
| case the client has attached to a site for the first time and is | ||||
| doing an initial syncronization, that is, retrieving a list of all | ||||
| the members of the collections and possibly retrieving all the | ||||
| members of the collection also. The client can perform a non-partial | ||||
| GET on the collection resource and it will receive a collection | ||||
| document that either contains all the member of the collection, or | ||||
| the collection document root element 'collection' will contain a | ||||
| 'next' attribute pointing to the next collection document. By | ||||
| repeatedly following the 'next' attribute from document to document | ||||
| the client can find all the members of the collection. | ||||
| In the second case the client has already done an initial sync, and | ||||
| now needs to re-sync, because the client was just restarted, or some | ||||
| time has passed since a re-sync, etc. The client does a partial GET | ||||
| on the collection document, supplying a Range header that begins from | ||||
| the last time the client sync'd to the current time. The collection | ||||
| document returned will contain only those members of the collection | ||||
| that have changed since the last time the client syncronized. | ||||
| 2.1.2 Client and Server Interaction | ||||
| [[anchor5: ...]] | ||||
| This document does not specify the form of the URIs that are used. | ||||
| The URI space of each server is controlled, as defined by HTTP, by | The URI space of each server is controlled, as defined by HTTP, by | |||
| the server alone. What this document does specify are the formats of | the server alone. What this document does specify are the formats of | |||
| the files that are exchanged and the actions that can be performed on | the files that are exchanged and the actions that can be performed on | |||
| the URIs embedded in those files. | the URIs embedded in those files. | |||
| 3. Functional Specification | 3. Functional Specification | |||
| 3.1 PostURI | 3.1 Collections | |||
| The PostURI is used to create entries. These can be either full | 3.1.1 Collection Document | |||
| entries, such as a weblog post, or they can be comments, or even a | ||||
| wiki page. The client POSTs a filled-in Atom Entry to this URI. If | ||||
| the request is successful, one or more Web resources MAY be created. | ||||
| For example, POSTing an Atom entry to a PostURI may create two new | ||||
| Web resources, an HTML representation and an Atom representation. | ||||
| 3.1.1 Locating the PostURI | A collection document is rooted by a <collection> element. A | |||
| collection element may have any number of <member> elements as | ||||
| children; each such element identifies a member of the collection. | ||||
| In some situations, a collection document may not contain every | ||||
| member of the collection itself. | ||||
| The PostURI can be discovered in a link element with an @rel of | Whether complete or partial, the members in a collection document | |||
| 'service.post'. The link element containing a PostURI used to create | MUST constitute a consecutive sequence of the collection's members, | |||
| a new entry MAY be discovered in three different places. The first | ordered by their "updated" properties. That is, a collection | |||
| place it may be found is in a <link> element in the 'head' element of | document MUST contain a contiguous subset of the members of the | |||
| an HTML document. | collection ordered by their 'updated' property. | |||
| The second place a PostURI may be found an atom:link element that is | 3.1.2 Elements in a Collection Document | |||
| a child of the atom:feed element. The third place a PostURI may be | ||||
| found is in the atom:link element of an atom:entry. | ||||
| @@ TBD @@ - Discuss subordinate resources and what a PostURI means | A collection document MAY contain zero or more 'member' elements. | |||
| based on where the URI was found. | ||||
| <link rel="service.post" | Each 'member' element MUST include an 'href' attribute identifying a | |||
| type="application/atom+xml" | URL of the member resource. The 'href' URI of a member resource is | |||
| href="URI for Posting goes here" | an "EditURI" under the terms of section 2, and MUST respond to the | |||
| title="The name of the site." /> | same HTTP methods as such an EditURI. | |||
| 3.1.2 Request | Each 'member' element MAY include an "hrefreadonly" attribute. This | |||
| optional attribute identifies a URI which, on a GET request, responds | ||||
| equivalently to how the "href" URI would respond to the same request. | ||||
| Clients SHOULD NOT apply to this URI any HTTP methods that would be | ||||
| expected to modify the state of the resource (e.g. PUT, POST or | ||||
| DELETE). A PUT or POST request to this URI MAY NOT affect the | ||||
| underlying resource. If the "hrefreadonly" attribute is not given, | ||||
| its value defaults to the "href" value. If the "hrefreadonly" | ||||
| attribute is present, and its value is an empty string, then there is | ||||
| no URI that can be treated in the way such a value would be treated. | ||||
| The request contains a filled-in Atom entry, subject to the | Clients SHOULD use the "href" value to manipulate the resource within | |||
| constraints in section Section 3.6. | the context of the APP itself. Clients SHOULD prefer the | |||
| "hrefreadonly" value in any other context. For example, if the | ||||
| resource is an image, a client may replace the image data using a PUT | ||||
| on the "href" value, and may even display a preview of the image by | ||||
| fetching the "href" URI. But when creating a public, read-only | ||||
| reference to the same image resource, the client should use the | ||||
| "hrefreadonly" value. If the "hrefreadonly" value is an empty | ||||
| string, the client SHOULD NOT make public reference to the "href" | ||||
| value. | ||||
| 3.1.3 Response | Each 'member' element MUST include a 'title' attribute, whose value | |||
| is a human-readable name or description for the item. The values of | ||||
| 'title' attributes are not required to be unique across all members | ||||
| of a collection. | ||||
| The possible status codes from a POST are 201, 303, 400, 404, 409, | Each 'member' element MUST include an 'updated' attribute, whose | |||
| 410 and 500. | value is the 'updated' property of the collection member whose format | |||
| MUST conform to the date-time BNF rule in [RFC3339]. | ||||
| 3.1.3.1 Response code 201 | 3.1.3 Collection Requests | |||
| The Response MUST include a Location: header with the URI of the | 3.1.3.1 Range: Header | |||
| created resource. The URI returned must be the EditURI of the entry | ||||
| just created. The body of the response SHOULD contain the newly | ||||
| created entry. If the entry is present in the response body then it | ||||
| MUST conform to the same constraints listed for responses to a GET on | ||||
| an EditURI. User agents MUST NOT depend on the server returning a | ||||
| response body. If the server does return a response body then the | ||||
| user agents MUST NOT depend on the response body having a | ||||
| content-type of 'application/atom+xml". Note that the server may | ||||
| choose to omit the content in the response, particularly if it is | ||||
| large. | ||||
| A 201 response MAY contain an ETag response header field indicating | HTTP/1.1 allows a client to request that only part (a range of) the | |||
| the current value of the entity tag for the requested variant just | collection to be included within the response. HTTP/1.1 uses range | |||
| created. | units in the Range header field. A collection can be broken down | |||
| into subranges according to the members 'updated' property. If a | ||||
| Range: header is present in the request, its value explictly | ||||
| identifies the a time interval interval in which all the members | ||||
| 'updated' property must fall to be included in the response. | ||||
| If the entry returned is subsequently changed the user agent can | Range = "Range" ":" ranges-specifier | |||
| update the entry by submitting it via PUT to the EditURI. If an ETag | ||||
| was returned with the creation of the entry then the user agent | ||||
| SHOULD include an If-Match: header in the request that contains that | ||||
| ETag. | ||||
| 3.1.3.2 Response code 303 | The value of the Range: header should be a pair of ISO 8601 dates, | |||
| separated by a slash character; either date may be optionally | ||||
| omitted, in which case the range is understood as stretching to | ||||
| infinity on that end. | ||||
| The body of this response does not contain the filled-in Entry, but | ranges-specifier = updated-ranges-specifier | |||
| the filled-in Entry can be found under a different URI and can be | updated-ranges-specifier = updated-unit "=" updated-range | |||
| retrieved using a GET method on that resource. The URI SHOULD be | updated-unit = "updated" | |||
| given by the Location field in the response. | updated-range = [iso-date] "/" [iso-date] | |||
| 3.1.3.3 Response code 400 | The response to a collection request MUST be a collection document, | |||
| all of whose 'member' elements fall within the requested range. If | ||||
| no members fall in the requested range, the server MUST respond with | ||||
| a collection document containing no 'member' elements. | ||||
| Indicates that the server believes that the data sent constitutes an | 3.1.3.2 Accept-Ranges: Header | |||
| invalid request. As an example, the data posted may not be | ||||
| well-formed XML. The server SHOULD include an entity containing an | ||||
| explanation of the error situation, and whether it is a temporary or | ||||
| permanent condition. | ||||
| 3.1.3.4 Response code 409 | The response to a non-partial GET request MUST include an | |||
| Accept-Ranges header that indicates that the server accepts 'updated' | ||||
| range requests. | ||||
| The request contained a valid Atom Entry, but it conflicts with state | Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges | |||
| on the server. The response SHOULD contain enough for information | acceptable-ranges = updated-unit ( 1#range-unit ) | |||
| for the user to resolve the conflict. | ||||
| [[@@TBD@@ more about response body format]] | 3.2 Introspection | |||
| 3.1.3.5 Response code 500 | There are many different kinds of resources that can be managed | |||
| through the APP, for example, entries, templates, users, etc. The | ||||
| Service Document is a single document that lists all the facets of | ||||
| the APP that a site supports and also contains the URIs of all those | ||||
| resources. | ||||
| Indicates that the server detected an internal error on the server | 3.2.1 Service Document | |||
| processing this request (such as an unhandled exception). The server | ||||
| SHOULD include an entity containing an explanation of the error | ||||
| situation, and whether it is a temporary or permanent condition. | ||||
| 3.2 EditURI | The Service Document lists the resources that each site makes | |||
| available. The Service Resource returns an Service Document in | ||||
| response to a GET request. Here is an example of an Service | ||||
| Document. | ||||
| An EditURI is used to edit a single entry. Each entry that is | <?xml version="1.0" encoding='utf-8'?> | |||
| <service version="0.3" xmlns="http://purl.org/atom/ns#"> | ||||
| <workspace title="Main Site" > | ||||
| <collection rel="entries" name="Entries" | ||||
| href="http://example.org/reilly/feed" /> | ||||
| <collection rel="categories" name="Categories" | ||||
| href="http://example.org/reilly/cat" /> | ||||
| <collection rel="templates" name="Templates" | ||||
| href="http://example.org/reilly/tmpl" /> | ||||
| <collection rel="users" name="Users" | ||||
| href="http://example.org/reilly/users" /> | ||||
| <collection rel="resource" name="Pictures" | ||||
| href="http://example.org/reilly/pic" /> | ||||
| </workspace> | ||||
| <workspace title="b-links"> | ||||
| <collection rel="entries" name="Entries" | ||||
| href="http://example.org/reilly/feed" /> | ||||
| <collection rel="http://example.net/booklist" name="Books" | ||||
| href="http://example.org/reilly/books" /> | ||||
| </workspace> | ||||
| </service> | ||||
| o entries | ||||
| o resource | ||||
| o categories | ||||
| o templates | ||||
| o users | ||||
| The default for the rel attribute is 'resource'. Extensibility for | ||||
| 'rel' values is handled in the same manner as PaceFieldingLinks. | ||||
| Each 'collection' element in 'workspace' represents a single facet of | ||||
| the APP. While a site must fully support each facet they list in | ||||
| their Service Document, a site does not need to support all the | ||||
| facets in this RFC. Additionally, new facets may be added either | ||||
| through vendor extension or follow-on RFCs. | ||||
| 3.2.1.1 Service Documet Elements | ||||
| The "service" element is the document element of a Service Document, | ||||
| acting as a container for service data associated with possibly | ||||
| multiple workspaces. Its only child elements MUST be one or more | ||||
| 'workspace' elements. The 'service' element MUST have a single | ||||
| attribute 'version' whose content indicates the version of the Atom | ||||
| specification that the document conforms to. The content of this | ||||
| attribute is unstructured text. The version identifier for this | ||||
| specification is "1.0". | ||||
| The 'workspace' element element contains information elements about | ||||
| the collections of resources available for editing. The only | ||||
| children of 'workspace' MUST be one or more "collection" elements. | ||||
| The 'workspace' element MUST have a single attribute 'title' whose | ||||
| content MUST NOT be empty and which is a human-readable name for the | ||||
| workspace. | ||||
| The 'collection' element describes various typed groups of resources | ||||
| available for editing or adding to. | ||||
| 3.3 Entry Collection | ||||
| Entries are managed through collections and as such entry collection | ||||
| and entries that are members of a collection must support all the | ||||
| operations enumerated above. | ||||
| An Edit Resource is used to edit a single entry. Each entry that is | ||||
| editable MUST have a unique URI. This URI supports both GET and PUT | editable MUST have a unique URI. This URI supports both GET and PUT | |||
| and they are used in tandem for an editing cycle. The client GETs | and they are used in tandem for an editing cycle. The client GETs | |||
| the representation which is formatted as an Atom entry. The client | the representation which is formatted as an Atom entry. The client | |||
| may then update the entry and then PUT it back to the same URI. The | may then update the entry and then PUT it back to the same URI. The | |||
| PUT will cause all the related resources to be updated, for example, | PUT will cause all the related resources to be updated, for example, | |||
| the HTML representation. | the HTML representation. | |||
| Note that the value of the content element in the Atom entry does not | Note that the value of the content element in the Atom entry does not | |||
| have to exactly match the content element for the same entry when it | have to exactly match the content element for the same entry when it | |||
| is represented in an Atom feed. For example, a server may allow the | is represented in an Atom feed. For example, a server may allow the | |||
| client to post entries whose content is formatted as WikiML, yet the | client to post entries whose content is formatted as WikiML, yet the | |||
| server may clean up such markup and transform it into well-formed | server may clean up such markup and transform it into well-formed | |||
| XHTML before placing it in the publicly available Atom feed. Another | XHTML before placing it in the publicly available Atom feed. Another | |||
| scenario is summaries--the EditURI is for editing the full content of | scenario is summaries--the EditURI is for editing the full content of | |||
| an entry, but the server may only present excerpts when it produces | an entry, but the server may only present excerpts when it produces | |||
| an Atom feed. | an Atom feed. | |||
| A client will send a DELETE to the EditURI to delete an entry. | A client will send a DELETE to the EditURI to delete an entry. | |||
| 3.2.1 Locating | 3.3.1 Locating | |||
| For editing a site Entry, the link tag is used. Note that a link tag | For editing a site Entry, the link tag is used. Note that a link tag | |||
| is used in both HTML and in the Atom format. A link tag of the | is used in both HTML and in the Atom format. A link tag of the | |||
| following format points to the EditURI for a site. In HTML, the link | following format points to the EditURI for a site. In HTML, the link | |||
| tags for editing are always found in the head element, while in Atom | tags for editing are always found in the head element, while in Atom | |||
| they may appear as children of the entry elements. | they may appear as children of the entry elements. | |||
| <link rel="service.edit" | <link rel="service.edit" | |||
| type="application/atom+xml" | type="application/atom+xml" | |||
| href="URI for Editing goes here" | href="URI for Editing goes here" | |||
| title="Readable desc of the entry." /> | title="Readable desc of the entry." /> | |||
| Note: The critical characteristic of this link tag is the @rel of | Note: The critical characteristic of this link tag is the @rel of | |||
| 'service.edit' and the @type of 'application/atom+xml'. | 'service.edit' and the @type of 'application/atom+xml'. | |||
| 3.2.2 Request | 3.4 Simple Resource Collection | |||
| A PUT request, and a GET response both contain a filled-in Atom | ||||
| entry, subject to the constraints in section Section 3.6. | ||||
| The expected status codes from a GET are 200, 301, 307, and 500. | ||||
| 400, 404, and 410 are also possible. | ||||
| The expected status codes from a PUT are 2xx, 301, 307, 500 and 501. | ||||
| 400, 404, 409, and 410 are also possible. | ||||
| 3.2.2.1 Successful Requests | ||||
| Servers MUST indicate successful GET requests with a 200 response. | ||||
| Servers MUST indicate successful PUT requests with a 2xx response. | ||||
| Servers MAY include additional information in the PUT response. | ||||
| Clients SHOULD NOT expect any additional information in a PUT | ||||
| response. | ||||
| 3.2.2.2 Response code 301 | ||||
| The entry has moved permanently, the new URI is given in the Location | ||||
| header. The client SHOULD retry the GET using the URI returned in | ||||
| the Location header. When a PUT operation is attempted the user | ||||
| agent should prompt the user before attempting the PUT on the URI | ||||
| returned in the Location header. | ||||
| 3.2.2.3 Response code 307 | ||||
| The entry has moved temporarily, the new URI is given in the Location | ||||
| header. The client SHOULD retry the GET using the URI returned in | ||||
| the Location header. When a PUT operation is attempted the user | ||||
| agent should prompt the user before attempting the PUT on the URI | ||||
| returned in the Location header. | ||||
| 3.2.2.4 Response code 401 | ||||
| Indicates that the server believes that the data sent constitutes an | ||||
| invalid request. As an example, the data posted may not be | ||||
| well-formed XML. The server SHOULD include an entity containing an | ||||
| explanation of the error situation, and whether it is a temporary or | ||||
| permanent condition. | ||||
| 3.2.2.5 Response code 409 | ||||
| The request contained a valid Atom Entry, but it conflicts with the | ||||
| state of the resource, or other state on the server. | ||||
| For example, a server could signal that the client has erred in this | ||||
| manner if it receives a request containing an atom:id element whose | ||||
| value differs from that of the resource found at the requested URI. | ||||
| The response SHOULD contain enough for information for the user to | ||||
| resolve the conflict. | ||||
| [[@@TBD@@ more about response body format ]] | ||||
| 3.2.2.6 Response code 410 | ||||
| Indicates that the requested resource is gone permanently. The | ||||
| client SHOULD NOT repeat the request. | ||||
| 3.2.2.7 Response code 500 | ||||
| Indicates that the server detected an internal error on the server | ||||
| processing this request (such as an unhandled exception). The server | ||||
| SHOULD include an entity containing an explanation of the error | ||||
| situation, and whether it is a temporary or permanent condition. | ||||
| 3.3 FeedURI | ||||
| The FeedURI is used to retrieve a representation in Atom format. | ||||
| Note that this feed is different from a typical Atom feed in that it | ||||
| contains "link" elements for navigating and manipulating the content | ||||
| of the site. For example there should be a "link" element with | ||||
| rel="next" whose URI points to the next block of entries on the site. | ||||
| Similarly, the feed element can contain a "link" element with | ||||
| rel="service.post", the URI of which is a PostURI. Individual | ||||
| entries should contain "link" elements with rel="service.edit" whose | ||||
| URIs are EditURIs. | ||||
| This document only uses some of the methods available for each type | ||||
| of URI. For example, the only method described by this document for | ||||
| the FeedURI is GET. Any other method may be supported by the URI | ||||
| types described, but defining their behavior is beyond the scope of | ||||
| this document. In this light you may notice that the PostURI only | ||||
| supports the POST method. It is possible, and allowable, that for | ||||
| some implementations the PostURI and the FeedURI are the same URI. | ||||
| @@ Editor's Note: @@ Note that the "service.feed" takes the place of | ||||
| the Introspection File and the Search facet in previous versions of | ||||
| the specification. That is, facet discovery, which was previously | ||||
| done by inspecting the Introspection file is now done by looking for | ||||
| "link" tags with an attribute "rel" set to "service.[something]" in | ||||
| the "service.feed" file. At the same time the same representation | ||||
| replaces the search facet by having "link" tags that point to other | ||||
| feeds using well-known 'rel' attribute values such as 'next' and | ||||
| 'prev', or the search can branch in multiple directions by specifying | ||||
| multiple link tags with rel="service.feed" and having differing title | ||||
| attributes that announce the kind of search results in that feed. | ||||
| 3.3.1 Locating | ||||
| A link tag of the following format points to the FeedURI. | ||||
| <link rel="service.feed" | ||||
| type="application/atom+xml" | ||||
| href="URI goes here" | ||||
| title="The name of the site." /> | ||||
| 3.3.2 Request | ||||
| The request is a simple GET. No other verbs are currently specified | ||||
| for this URI. | ||||
| 3.3.3 Response | ||||
| The expected status codes from a GET are 200, 301, 307, and 500. | ||||
| 401, 404, and 410 are also possible. | ||||
| 3.3.3.1 Response code 301 | ||||
| The Feed has moved permanently, the new URI is given in the Location | ||||
| header. The client SHOULD do a GET on the URI returned in the | ||||
| Location header. | ||||
| 3.3.3.2 Response code 307 | ||||
| The Feed has moved temporarily, the new URI is given in the Location | ||||
| header. The client SHOULD do a GET on the URI returned in the | ||||
| Location header. | ||||
| 3.4 ResourcePostURI | ||||
| The ResourcePostURI is used to create new non-entry resources. The | Simple Resources are managed through collections and as such simple | |||
| client POSTs a resource of the desired MIME type directly to this | reource collections and simple resources that are members of the | |||
| URI. | collection must support all the operations enumerated above. Simple | |||
| Resources can be images, templates, and any other non-entry | ||||
| resources. | ||||
| 3.4.1 Locating | 3.4.1 Locating | |||
| For creating a new non-entry resource, the link tag is used. Note | For creating a new non-entry resource, the link tag is used. Note | |||
| that a link tag is used in both HTML and in the Atom format. A link | that a link tag is used in both HTML and in the Atom format. A link | |||
| tag of the following format points to the ResourcePostURI for a site. | tag of the following format points to the ResourcePostURI for a site. | |||
| In HTML the link tags are always found in the head element, while in | In HTML the link tags are always found in the head element, while in | |||
| Atom they may appear as children of the Feed and entry elements. | Atom they may appear as children of the Feed and entry elements. | |||
| <link rel="resource.post" href="URI for Resource Posting goes here" | <link rel="resource.post" href="URI for Resource Posting goes here" | |||
| skipping to change at page 11, line 20 | skipping to change at page 11, line 5 | |||
| The request contains a resource, sent through a standard HTTP POST, | The request contains a resource, sent through a standard HTTP POST, | |||
| e.g.: | e.g.: | |||
| POST /_do/exampleblog/post_resource HTTP/1.1 | POST /_do/exampleblog/post_resource HTTP/1.1 | |||
| Host: www.example.com | Host: www.example.com | |||
| Content-Type: image/jpeg | Content-Type: image/jpeg | |||
| Content-Length: nnn | Content-Length: nnn | |||
| ...raw bytes of image go here... | ...raw bytes of image go here... | |||
| 3.4.3 Response | 3.5 Atom Request and Response Body Constraints | |||
| The expected status codes from a POST are 201, 303, 400, 415, and | ||||
| 500. 401, 404, 409, and 410 are also possible. | ||||
| 3.4.3.1 Response code 201 | ||||
| The response MUST include a Location: header with the URI of the | ||||
| created resource, i.e. the URI used to retrieve the resource | ||||
| representation in a subsequent HTTP GET. The server SHOULD omit the | ||||
| content of the resource in the response, since it would be redundant | ||||
| to return it to the client. | ||||
| 3.4.3.2 Response code 303 | ||||
| Similar to 201 but no caching is allowed. The response MUST include | ||||
| a Location: header. | ||||
| 3.4.3.3 Response code 400 | ||||
| Indicates that the server believes that the data sent constitutes an | ||||
| invalid request. The server SHOULD include an entity containing an | ||||
| explanation of the error situation, and whether it is a temporary or | ||||
| permanent condition. | ||||
| 3.4.3.4 Response code 415 | ||||
| The MIME type of the request entity is not supported by the server | ||||
| for this resource. | ||||
| The response SHOULD contain enough for information for the user to | ||||
| resolve the conflict. | ||||
| [[@@TBD@@ more about response body format ]] | ||||
| 3.4.3.5 Response code 500 | ||||
| Indicates that the server detected an internal error on the server | ||||
| processing this request (such as an unhandled exception). A short | ||||
| description of the error will appear on the status line itself. A | ||||
| longer description will appear in the body. | ||||
| 3.5 Link Tag | ||||
| The link tag is used in both HTML and Atom formats. There are slight | ||||
| differences between the two usages. Here are the commonalities, | ||||
| differences, and a list of well-known values for the rel attribute. | ||||
| <http://www.w3.org/TR/html4/struct/links.html#edef-LINK> appears in | ||||
| the 'head' of the document. The 'head' section only allows a linear | ||||
| list of 'link' tags. The Atom format allows 'link' tags as children | ||||
| of both the 'feed' element and of the 'entry' element. Note that | ||||
| this gives the information present in the link tag more context. For | ||||
| example ... @@ TBD @@ | ||||
| 3.5.1 rel | ||||
| This attribute describes the relationship from the current document, | ||||
| be it HTML or Atom, to the anchor specified by the href attribute. | ||||
| The value of this attribute is a space-separated list of link types. | ||||
| Note that these values are case insensitive. When used in concert | ||||
| with type="application/atom+xml", the relations may be interpreted as | ||||
| follows. | ||||
| alternate: The URI in the href attribute points to an alternate | ||||
| representation of the containing resource. | ||||
| start: The Atom feed at the URI supplied in the href attribute | ||||
| contains the first feed in a linear sequence of entries. | ||||
| next: The Atom feed at the URI supplied in the href attribute | ||||
| contains the next N entries in a linear sequence of entries. | ||||
| prev: The Atom feed at the URI supplied in the href attribute | ||||
| contains the previous N entries in a linear sequence of entries. | ||||
| service.edit: The URI given in the href attribute is used to edit a | ||||
| representation of the referred resource. | ||||
| service.post: The URI in the href attribute is used to create new | ||||
| resources. | ||||
| service.feed: The URI given in the href attribute is a starting point | ||||
| for navigating content and services. | ||||
| 3.5.2 href | ||||
| URI of the resource being described by this link element. | ||||
| 3.5.3 title | ||||
| Offers advisory information about the link. Rendered to the user to | ||||
| help them choose among a set of links with the same rel and type | ||||
| attributes. | ||||
| 3.5.4 type | ||||
| The content type of the resource available at the URI given in the | ||||
| href attribute of the link element. Most of the link types in this | ||||
| specification are on type 'application/atom+xml'. | ||||
| 3.6 Atom Request and Response Body Constraints | ||||
| The Atom format is used as the representation of all the resources in | The Atom format is used as the representation of all the resources in | |||
| this specification. As it is used in differing contexts, there are | this specification. As it is used in differing contexts, there are | |||
| different constraints of which elements may be present, and how their | different constraints of which elements may be present, and how their | |||
| values should be interpreted. | values should be interpreted. | |||
| 3.6.1 id | 3.5.1 id | |||
| PostURI MUST NOT be present. | PostURI MUST NOT be present. | |||
| FeedURI MUST be present. | FeedURI MUST be present. | |||
| EditURI | EditURI | |||
| GET MUST be present. | GET MUST be present. | |||
| PUT MUST be present. | PUT MUST be present. | |||
| 3.6.2 link | 3.5.2 link | |||
| PostURI MAY be present. Servers MAY use the information to determine | PostURI MAY be present. Servers MAY use the information to determine | |||
| the URI of the created resource. Relative URLs are to be | the URI of the created resource. Relative URLs are to be | |||
| interpreted relative to xml:base. | interpreted relative to xml:base. | |||
| FeedURI MUST be present. | FeedURI MUST be present. | |||
| EditURI | EditURI | |||
| GET MUST be present. | GET MUST be present. | |||
| PUT MUST be present. | PUT MUST be present. | |||
| 3.6.3 title | 3.5.3 title | |||
| PostURI MUST be present. The element may be empty, to explicitly | PostURI MUST be present. The element may be empty, to explicitly | |||
| indicate "no title". Servers SHOULD NOT try to generate a title | indicate "no title". Servers SHOULD NOT try to generate a title | |||
| if one is not provided. The type attribute MAY be present, and if | if one is not provided. The type attribute MAY be present, and if | |||
| not it defaults to "text/plain". If present, it MUST represent a | not it defaults to "text/plain". If present, it MUST represent a | |||
| MIME type that the server supports. The mode attribute MAY be | MIME type that the server supports. The mode attribute MAY be | |||
| present. If not present, it defaults to "xml". If present, it | present. If not present, it defaults to "xml". If present, it | |||
| MUST be "xml", "base64", or "escaped". | MUST be "xml", "base64", or "escaped". | |||
| FeedURI MUST be present. | FeedURI MUST be present. | |||
| EditURI | EditURI | |||
| GET MUST be present. | GET MUST be present. | |||
| PUT MUST be present. The element may be empty, to explicitly | PUT MUST be present. The element may be empty, to explicitly | |||
| indicate "no title". Servers SHOULD NOT try to generate a | indicate "no title". Servers SHOULD NOT try to generate a | |||
| title if one is not provided. | title if one is not provided. | |||
| 3.6.4 summary | 3.5.4 summary | |||
| PostURI MAY be present. If not present, the server is welcome to | PostURI MAY be present. If not present, the server is welcome to | |||
| produce its own summary. If present but empty, the server SHOULD | produce its own summary. If present but empty, the server SHOULD | |||
| NOT generate a summary of its own. The type attribute MAY be | NOT generate a summary of its own. The type attribute MAY be | |||
| present. If not, it defaults to "text/plain". If present, it | present. If not, it defaults to "text/plain". If present, it | |||
| must represent a MIME type that the server supports. The mode | must represent a MIME type that the server supports. The mode | |||
| attribute MAY be present and defaults to "xml". If present, it | attribute MAY be present and defaults to "xml". If present, it | |||
| must be "xml","base64", or "escaped". | must be "xml","base64", or "escaped". | |||
| FeedURI MAY be present. | FeedURI MAY be present. | |||
| EditURI | EditURI | |||
| GET MAY be present. | GET MAY be present. | |||
| PUT MAY be present. The element may be empty, to explicitly | PUT MAY be present. The element may be empty, to explicitly | |||
| indicate "no summary". Servers SHOULD NOT try to generate a | indicate "no summary". Servers SHOULD NOT try to generate a | |||
| title if one is not provided. | title if one is not provided. | |||
| 3.6.5 content | 3.5.5 content | |||
| PostURI MAY be present but may be empty, to explicitly indicate "no | PostURI MAY be present but may be empty, to explicitly indicate "no | |||
| content". The type attribute MAY be present, but defaults to | content". The type attribute MAY be present, but defaults to | |||
| "text/plain" if not present. It must represent a MIME type that | "text/plain" if not present. It must represent a MIME type that | |||
| the server supports. The MODE attribute may be present and | the server supports. The MODE attribute may be present and | |||
| defaults to "xml" if not present. It must be "xml","base64", or | defaults to "xml" if not present. It must be "xml","base64", or | |||
| "escaped". | "escaped". | |||
| FeedURI MAY be present. | FeedURI MAY be present. | |||
| EditURI | EditURI | |||
| GET MAY be present. | GET MAY be present. | |||
| PUT MAY be present. The element may be empty, to explicitly | PUT MAY be present. The element may be empty, to explicitly | |||
| indicate "no content". | indicate "no content". | |||
| 3.6.6 issued | 3.5.6 issued | |||
| PostURI MUST be present, but may be empty, in which case it signifies | PostURI MUST be present, but may be empty, in which case it signifies | |||
| "now" in the time zone of the server. | "now" in the time zone of the server. | |||
| FeedURI MUST be present. | FeedURI MUST be present. | |||
| EditURI | EditURI | |||
| GET MUST be present. | GET MUST be present. | |||
| PUT MUST be present. Server policy determines if an updated time | PUT MUST be present. Server policy determines if an updated time | |||
| is accepted. | is accepted. | |||
| 3.6.7 modified | 3.5.7 modified | |||
| PostURI MUST NOT be present. | PostURI MUST NOT be present. | |||
| FeedURI MAY be present. | FeedURI MAY be present. | |||
| EditURI | EditURI | |||
| GET MAY be present. | GET MAY be present. | |||
| PUT MAY be present. The element may be empty, to explicitly | PUT MAY be present. The element may be empty, to explicitly | |||
| indicate that 'now' on the server time is to be used. | indicate that 'now' on the server time is to be used. | |||
| 3.6.8 created | 3.5.8 created | |||
| PostURI MAY be present. | PostURI MAY be present. | |||
| FeedURI MAY be present. | FeedURI MAY be present. | |||
| EditURI | EditURI | |||
| GET MAY be present. | GET MAY be present. | |||
| PUT MAY be present. The server may or may not accept an updated | PUT MAY be present. The server may or may not accept an updated | |||
| value. If the server does not allow updating the issued time | value. If the server does not allow updating the issued time | |||
| then any PUT request with a different issued value MUST be | then any PUT request with a different issued value MUST be | |||
| rejected. | rejected. | |||
| 3.6.9 author | 3.5.9 author | |||
| PostURI MAY be present. If not present, the server determines the | PostURI MAY be present. If not present, the server determines the | |||
| author. If present, and conflicting with valid values as | author. If present, and conflicting with valid values as | |||
| determined by the server, then the server may change the value of | determined by the server, then the server may change the value of | |||
| author. | author. | |||
| FeedURI MAY be present. | FeedURI MAY be present. | |||
| EditURI | EditURI | |||
| GET MAY be present. | GET MAY be present. | |||
| PUT MAY be present. | PUT MAY be present. | |||
| 3.6.10 contributor | 3.5.10 contributor | |||
| PostURI MAY be present. | PostURI MAY be present. | |||
| FeedURI MAY be present. | FeedURI MAY be present. | |||
| EditURI | EditURI | |||
| GET MAY be present. | GET MAY be present. | |||
| PUT MAY be present. | PUT MAY be present. | |||
| 3.6.11 generator | 3.5.11 generator | |||
| PostURI MUST be present and contain a URI. The value of the element | PostURI MUST be present and contain a URI. The value of the element | |||
| indicates the code base used to create this request. MUST also | indicates the code base used to create this request. MUST also | |||
| have an attribute 'version' with a version number. | have an attribute 'version' with a version number. | |||
| FeedURI MUST NOT be present. | FeedURI MUST NOT be present. | |||
| EditURI | EditURI | |||
| GET MUST NOT be present. | GET MUST NOT be present. | |||
| PUT MUST NOT be present. | PUT MUST NOT be present. | |||
| 3.7 Securing the Atom Protocol | 3.6 Securing the Atom Protocol | |||
| All instances of publishing Atom entries SHOULD be protected by | All instances of publishing Atom entries SHOULD be protected by | |||
| authentication to prevent posting or editing by unknown sources. | authentication to prevent posting or editing by unknown sources. | |||
| Atom servers and clients MUST support one of the following | Atom servers and clients MUST support one of the following | |||
| authentication mechanisms, and SHOULD support both. | authentication mechanisms, and SHOULD support both. | |||
| o HTTP Digest Authentication [RFC2617] | o HTTP Digest Authentication [RFC2617] | |||
| o [@@TBD@@ CGI Authentication ref] | o [@@TBD@@ CGI Authentication ref] | |||
| Atom servers and clients MAY support encryption of the Atom session | Atom servers and clients MAY support encryption of the Atom session | |||
| using TLS [RFC2246]. | using TLS [RFC2246]. | |||
| There are cases where an authentication mechanism may not be | There are cases where an authentication mechanism may not be | |||
| required, such as a publicly editable Wiki, or when using the PostURI | required, such as a publicly editable Wiki, or when using the PostURI | |||
| to post comments to a site that does not require authentication to | to post comments to a site that does not require authentication to | |||
| create comments. | create comments. | |||
| 3.7.1 [@@TBD@@ CGI Authentication] | 3.6.1 [@@TBD@@ CGI Authentication] | |||
| This authentication method is included as part of the protocol to | This authentication method is included as part of the protocol to | |||
| allow Atom servers and clients that cannot use HTTP Digest | allow Atom servers and clients that cannot use HTTP Digest | |||
| Authentication but where the user can both insert its own HTTP | Authentication but where the user can both insert its own HTTP | |||
| headers and create a CGI program to authenticate entries to the | headers and create a CGI program to authenticate entries to the | |||
| server. This scenario is common in environments where the user | server. This scenario is common in environments where the user | |||
| cannot control what services the server employs, but the user can | cannot control what services the server employs, but the user can | |||
| write their own HTTP services. | write their own HTTP services. | |||
| 4. Security Considerations | 4. Security Considerations | |||
| skipping to change at page 18, line 15 | skipping to change at page 15, line 52 | |||
| the 'introspection' file. 1. Creating a new entry 2. Finding an | the 'introspection' file. 1. Creating a new entry 2. Finding an | |||
| old entry 3. editing an old entry 4. commenting on a entry (via | old entry 3. editing an old entry 4. commenting on a entry (via | |||
| HTML and Atom) | HTML and Atom) | |||
| 7.2 Example for a wiki | 7.2 Example for a wiki | |||
| Fill this in like above but for a wiki. | Fill this in like above but for a wiki. | |||
| 8. Revision History | 8. Revision History | |||
| draft-ietf-atompub-protocol-03 - Incorporates PaceSliceAndDice3 and | ||||
| PaceIntrospection. | ||||
| draft-ietf-atompub-protocol-02 - Incorporates Pace409Response, | draft-ietf-atompub-protocol-02 - Incorporates Pace409Response, | |||
| PacePostLocationMust, and PaceSimpleResourcePosting. | PacePostLocationMust, and PaceSimpleResourcePosting. | |||
| draft-ietf-atompub-protocol-01 - Added in sections on Responses for | draft-ietf-atompub-protocol-01 - Added in sections on Responses for | |||
| the EditURI. Allow 2xx for response to EditURI PUTs. Elided all | the EditURI. Allow 2xx for response to EditURI PUTs. Elided all | |||
| mentions of WSSE. Started adding in some normative references. | mentions of WSSE. Started adding in some normative references. | |||
| Added the section "Securing the Atom Protocol". Clarified that it is | Added the section "Securing the Atom Protocol". Clarified that it is | |||
| possible that the PostURI and FeedURI could be the same URI. Cleaned | possible that the PostURI and FeedURI could be the same URI. Cleaned | |||
| up descriptions for Response codes 400 and 500. | up descriptions for Response codes 400 and 500. | |||
| skipping to change at page 19, line 32 | skipping to change at page 17, line 22 | |||
| instead they are retrieved via GET. Cleaned up figure titles, as | instead they are retrieved via GET. Cleaned up figure titles, as | |||
| they are rendered poorly in HTML. All content-types have been | they are rendered poorly in HTML. All content-types have been | |||
| changed to application/atom+xml. | changed to application/atom+xml. | |||
| Rev 01 - 5Jul2003 - Renamed from EchoAPI.html to follow the more | Rev 01 - 5Jul2003 - Renamed from EchoAPI.html to follow the more | |||
| commonly used format: draft-gregorio-NN.html. Renamed all references | commonly used format: draft-gregorio-NN.html. Renamed all references | |||
| to URL to URI. Broke out introspection into it's own section. Added | to URL to URI. Broke out introspection into it's own section. Added | |||
| the Revision History section. Added more to the warning that the | the Revision History section. Added more to the warning that the | |||
| example URIs are not normative. | example URIs are not normative. | |||
| 9 Normative References | 9. Normative References | |||
| [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |||
| Requirement Levels", BCP 14, RFC 2119, March 1997. | Requirement Levels", BCP 14, RFC 2119, March 1997. | |||
| [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", | [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", | |||
| RFC 2246, January 1999. | RFC 2246, January 1999. | |||
| [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform | [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform | |||
| Resource Identifiers (URI): Generic Syntax", RFC 2396, | Resource Identifiers (URI): Generic Syntax", RFC 2396, | |||
| August 1998. | August 1998. | |||
| [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., | [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., | |||
| Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext | Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext | |||
| Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. | Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. | |||
| [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., | [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., | |||
| Leach, P., Luotonen, A. and L. Stewart, "HTTP | Leach, P., Luotonen, A. and L. Stewart, "HTTP | |||
| Authentication: Basic and Digest Access Authentication", | Authentication: Basic and Digest Access Authentication", | |||
| RFC 2617, June 1999. | RFC 2617, June 1999. | |||
| [1] <http://www.imc.org/atom-syntax/index.html> | ||||
| Authors' Addresses | Authors' Addresses | |||
| Joe Gregorio (editor) | Joe Gregorio (editor) | |||
| BitWorking, Inc | BitWorking, Inc | |||
| 1002 Heathwood Dairy Rd. | 1002 Heathwood Dairy Rd. | |||
| Apex, NC 27502 | Apex, NC 27502 | |||
| US | US | |||
| Phone: +1 919 272 3764 | Phone: +1 919 272 3764 | |||
| EMail: joe@bitworking.com | Email: joe@bitworking.com | |||
| URI: http://bitworking.com/ | URI: http://bitworking.com/ | |||
| Robert Sayre (editor) | Robert Sayre (editor) | |||
| Boswijck Memex Consulting | Boswijck Memex Consulting | |||
| 148 N 9th St. 4R | 148 N 9th St. 4R | |||
| Brooklyn, NY 11211 | Brooklyn, NY 11211 | |||
| US | US | |||
| EMail: rfsayre@boswijck.com | Email: rfsayre@boswijck.com | |||
| URI: http://boswijck.com | URI: http://boswijck.com | |||
| Intellectual Property Statement | Intellectual Property Statement | |||
| The IETF takes no position regarding the validity or scope of any | The IETF takes no position regarding the validity or scope of any | |||
| Intellectual Property Rights or other rights that might be claimed to | Intellectual Property Rights or other rights that might be claimed to | |||
| pertain to the implementation or use of the technology described in | pertain to the implementation or use of the technology described in | |||
| this document or the extent to which any license under such rights | this document or the extent to which any license under such rights | |||
| might or might not be available; nor does it represent that it has | might or might not be available; nor does it represent that it has | |||
| made any independent effort to identify any such rights. Information | made any independent effort to identify any such rights. Information | |||
| skipping to change at page 21, line 46 | skipping to change at page 19, line 46 | |||
| This document and the information contained herein are provided on an | This document and the information contained herein are provided on an | |||
| "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS | "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS | |||
| OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET | OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET | |||
| ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, | ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, | |||
| INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE | INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE | |||
| INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED | INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED | |||
| WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. | WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. | |||
| Copyright Statement | Copyright Statement | |||
| Copyright (C) The Internet Society (2004). This document is subject | Copyright (C) The Internet Society (2005). This document is subject | |||
| to the rights, licenses and restrictions contained in BCP 78, and | to the rights, licenses and restrictions contained in BCP 78, and | |||
| except as set forth therein, the authors retain all their rights. | except as set forth therein, the authors retain all their rights. | |||
| Acknowledgment | Acknowledgment | |||
| Funding for the RFC Editor function is currently provided by the | Funding for the RFC Editor function is currently provided by the | |||
| Internet Society. | Internet Society. | |||
| End of changes. | ||||
This html diff was produced by rfcdiff 1.12, available from http://www.levkowetz.com/ietf/tools/rfcdiff/ | ||||