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/ |