idnits 2.17.1
draft-ietf-atompub-protocol-04.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
** It looks like you're using RFC 3978 boilerplate. You should update this
to the boilerplate described in the IETF Trust License Policy document
(see https://trustee.ietf.org/license-info), which is required now.
-- Found old boilerplate from RFC 3978, Section 5.1 on line 14.
-- Found old boilerplate from RFC 3978, Section 5.5 on line 1207.
-- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1179.
-- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1186.
-- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1192.
** This document has an original RFC 3978 Section 5.4 Copyright Line,
instead of the newer IETF Trust Copyright according to RFC 4748.
** This document has an original RFC 3978 Section 5.5 Disclaimer, instead
of the newer disclaimer which includes the IETF Trust according to RFC
4748.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
== No 'Intended status' indicated for this document; assuming Proposed
Standard
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The abstract seems to contain references ([1]), which it shouldn't.
Please replace those with straight textual mentions of the documents in
question.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the RFC 3978 Section 5.4 Copyright Line does not
match the current year
-- The exact meaning of the all-uppercase expression 'MAY NOT' is not
defined in RFC 2119. If it is intended as a requirements expression, it
should be rewritten using one of the combinations defined in RFC 2119;
otherwise it should not be all-uppercase.
== The expression 'MAY NOT', while looking like RFC 2119 requirements text,
is not defined in RFC 2119, and should not be used. Consider using 'MUST
NOT' instead (if that is what you mean).
Found 'MAY NOT' in this paragraph:
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 document seems to lack a disclaimer for pre-RFC5378 work, but may
have content which was first submitted before 10 November 2008. If you
have contacted all the original authors and they are all willing to grant
the BCP78 rights to the IETF Trust, then this is fine, and you can ignore
this comment. If not, you may need to add the pre-RFC5378 disclaimer.
(See the Legal Provisions document at
https://trustee.ietf.org/license-info for more information.)
-- The document date (May 9, 2005) is 6926 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
-- Possible downref: Non-RFC (?) normative reference: ref. 'AtomFormat'
** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346)
** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231,
RFC 7232, RFC 7233, RFC 7234, RFC 7235)
** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615,
RFC 7616, RFC 7617)
** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303)
Summary: 8 errors (**), 0 flaws (~~), 3 warnings (==), 9 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
1 Network Working Group J. Gregorio, Ed.
2 Internet-Draft BitWorking, Inc
3 Expires: November 10, 2005 R. Sayre, Ed.
4 May 9, 2005
6 The Atom Publishing Protocol
7 draft-ietf-atompub-protocol-04.txt
9 Status of this Memo
11 By submitting this Internet-Draft, each author represents that any
12 applicable patent or other IPR claims of which he or she is aware
13 have been or will be disclosed, and any of which he or she becomes
14 aware will be disclosed, in accordance with Section 6 of BCP 79.
16 Internet-Drafts are working documents of the Internet Engineering
17 Task Force (IETF), its areas, and its working groups. Note that
18 other groups may also distribute working documents as Internet-
19 Drafts.
21 Internet-Drafts are draft documents valid for a maximum of six months
22 and may be updated, replaced, or obsoleted by other documents at any
23 time. It is inappropriate to use Internet-Drafts as reference
24 material or to cite them other than as "work in progress."
26 The list of current Internet-Drafts can be accessed at
27 http://www.ietf.org/ietf/1id-abstracts.txt.
29 The list of Internet-Draft Shadow Directories can be accessed at
30 http://www.ietf.org/shadow.html.
32 This Internet-Draft will expire on November 10, 2005.
34 Copyright Notice
36 Copyright (C) The Internet Society (2005).
38 Abstract
40 This memo presents a protocol for using XML (Extensible Markup
41 Language) and HTTP (HyperText Transport Protocol) to edit content.
43 The Atom Publishing Protocol is an application-level protocol for
44 publishing and editing Web resources belonging to periodically
45 updated websites. The protocol at its core is the HTTP transport of
46 Atom-formatted representations. The Atom format is documented in the
47 Atom Syndication Format (draft-ietf-atompub-format-06.txt).
49 Editorial Note
51 To provide feedback on this Internet-Draft, join the atom-protocol
52 mailing list (http://www.imc.org/atom-protocol/index.html) [1].
54 Table of Contents
56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
57 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 4
58 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
59 4. The Atom Publishing Protocol Model . . . . . . . . . . . . . . 6
60 4.1 Collections . . . . . . . . . . . . . . . . . . . . . . . 6
61 4.2 Discovery . . . . . . . . . . . . . . . . . . . . . . . . 6
62 4.3 Listing . . . . . . . . . . . . . . . . . . . . . . . . . 7
63 4.4 Authoring . . . . . . . . . . . . . . . . . . . . . . . . 7
64 4.4.1 Create . . . . . . . . . . . . . . . . . . . . . . . . 7
65 4.4.2 Read . . . . . . . . . . . . . . . . . . . . . . . . . 8
66 4.4.3 Update . . . . . . . . . . . . . . . . . . . . . . . . 8
67 4.4.4 Delete . . . . . . . . . . . . . . . . . . . . . . . . 8
68 4.5 Success and Failure . . . . . . . . . . . . . . . . . . . 9
69 5. Collections . . . . . . . . . . . . . . . . . . . . . . . . . 10
70 5.1 Collection Documents . . . . . . . . . . . . . . . . . . . 10
71 5.1.1 Element Definitions . . . . . . . . . . . . . . . . . 10
72 5.2 Collection Resource . . . . . . . . . . . . . . . . . . . 12
73 5.2.2 POST . . . . . . . . . . . . . . . . . . . . . . . . . 14
74 5.2.3 Usage Scenarios . . . . . . . . . . . . . . . . . . . 15
75 5.2.4 Range: Header . . . . . . . . . . . . . . . . . . . . 16
76 5.2.5 Accept-Ranges: Header . . . . . . . . . . . . . . . . 16
77 5.2.6 Name: Header . . . . . . . . . . . . . . . . . . . . . 17
78 6. Entry Collection . . . . . . . . . . . . . . . . . . . . . . . 18
79 6.1 Editing Entry Resources . . . . . . . . . . . . . . . . . 18
80 6.2 Role of Atom Entry Elements During Editing . . . . . . . . 18
81 7. Generic Collection . . . . . . . . . . . . . . . . . . . . . . 20
82 7.1 Editing Generic Resources . . . . . . . . . . . . . . . . 20
83 8. Introspection . . . . . . . . . . . . . . . . . . . . . . . . 21
84 8.1 Introspection Document . . . . . . . . . . . . . . . . . . 21
85 8.1.1 Element Definitions . . . . . . . . . . . . . . . . . 21
86 8.2 Introspection Resource . . . . . . . . . . . . . . . . . . 23
87 8.2.1 Discovery . . . . . . . . . . . . . . . . . . . . . . 24
88 9. Securing the Atom Protocol . . . . . . . . . . . . . . . . . . 25
89 10. Security Considerations . . . . . . . . . . . . . . . . . . 26
90 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . 27
91 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 30
92 12.1 Normative References . . . . . . . . . . . . . . . . . . . 30
93 12.2 Informative References . . . . . . . . . . . . . . . . . . 31
94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 32
95 A. Revision History . . . . . . . . . . . . . . . . . . . . . . . 33
96 Intellectual Property and Copyright Statements . . . . . . . . 35
98 1. Introduction
100 The Atom Publishing Protocol is an application-level protocol for
101 publishing and editing Web resources using HTTP [RFC2616] and XML 1.0
102 [W3C.REC-xml-20040204].
104 2. Notational Conventions
106 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
107 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
108 document are to be interpreted as described in [RFC2119].
110 3. Terminology
112 URI/IRI - A Uniform Resource Identifier and Internationalized
113 Resource Identifier, respectively. These terms (and the distinction
114 between them) are defined in [RFC3986] and [RFC3987].
116 Resource - an item identified by a URI [W3C.REC-webarch-20041215].
118 Collection Resource - A resource that contains a listing of Member
119 Resources and meets the requirements in Section 5 of this
120 specification.
122 Member Resource - A resource whose URI is listed by a Collection
123 Resource.
125 4. The Atom Publishing Protocol Model
127 The Atom Publishing Protocol operates on collections of Web
128 resources. All collections support the same basic interactions, as
129 do the resources within the collections. The patterns of interaction
130 are based on the common HTTP verbs.
132 o GET is used to retrieve a representation of a resource or perform
133 a read-only query.
135 o POST is used to create a new, dynamically-named resource.
137 o PUT is used to update a known resource.
139 o DELETE is used to remove a resource.
141 4.1 Collections
143 The APP groups resources into "Collections", which are analogous to
144 the "folders" or "directories" found in many file systems.
146 4.2 Discovery
148 To discover the location of the collections exposed by an APP
149 service, the client must locate and request an Introspection Document
150 (Section 8).
152 Client Server
153 | |
154 | 1.) GET Introspection |
155 |------------------------------->|
156 | |
157 | 2.) Introspection Doc |
158 |<-------------------------------|
159 | |
161 1. The client sends a GET request to the Service Description
162 Resource.
164 2. The server responds with an Introspection Document containing the
165 locations of collections provided by the service. The content of
166 this document can vary based on aspects of the client request,
167 including, but not limited to, authentication credentials.
169 4.3 Listing
171 Once the client has discovered the location of a collection, it can
172 request a listing of the collection's membership. However,
173 collections might be extremely large, so servers are likely to list a
174 small subset of the collection by default.
176 Client Server
177 | |
178 | 1.) GET to Collection URI |
179 |------------------------------->|
180 | |
181 | 2.) 200 OK, Atom Feed Doc |
182 |<-------------------------------|
183 | |
185 1. The client sends a GET request to the Collection's URI.
187 2. The server responds with an Atom Feed Document containing a full
188 or partial listing of the collection's membership.
190 4.4 Authoring
192 After locating a collection, a client can add entries by sending a
193 request to the collection; other changes are accomplished by sending
194 HTTP requests to its member resources.
196 4.4.1 Create
198 Client Server
199 | |
200 | 1.) POST to Collection URI |
201 |------------------------------->|
202 | |
203 | 2.) 201 Created @ Location |
204 |<-------------------------------|
205 | |
207 1. The client sends a representation of a member to the server via
208 HTTP POST. The Request URI is that of the Collection.
210 2. The server responds with a response of "201 Created" and a
211 "Location" header containing the URI of the newly-created
212 resource.
214 4.4.2 Read
216 Client Server
217 | |
218 | 1.) GET or HEAD to Member URI |
219 |------------------------------->|
220 | |
221 | 2.) 200 OK |
222 |<-------------------------------|
223 | |
225 1. The client sends a GET (or HEAD) request to the member's URI.
227 2. The server responds with an appropriate representation.
229 4.4.3 Update
231 Client Server
232 | |
233 | 1.) PUT to Member URI |
234 |------------------------------->|
235 | |
236 | 2.) 200 OK |
237 |<-------------------------------|
239 1. The client PUTs an updated representation to the member's URI.
241 2. The server responds with a representation of the member's new
242 state.
244 4.4.4 Delete
246 Client Server
247 | |
248 | 1.) DELETE to Member URI |
249 |------------------------------->|
250 | |
251 | 2.) 204 No Content |
252 |<-------------------------------|
253 | |
255 1. The client sends a DELETE request to the member's URI.
257 2. The server responds with successful status code.
259 4.5 Success and Failure
261 HTTP defines classes of response. HTTP status codes of the form 2xx
262 signal that a request was successful. HTTP status codes of the form
263 4xx or 5xx signal that an error has occurred, and the request has
264 failed. Consult the HTTP specification for more detailed definitions
265 of each status code.
267 5. Collections
269 An Atom Collection is a set of related resources. All members of a
270 collection have an "updated" property, and the collection is
271 considered to be ordered by this property.
273 5.1 Collection Documents
275 An example Collection Document.
277
278
279
283
287
291
294
296 Atom Collection Documents have the media-type 'application/
297 atomcoll+xml', see Section 11.
299 5.1.1 Element Definitions
301 5.1.1.1 The 'app:collection' Element
303 The 'app:collection' element represents an Atom Collection. A
304 collection document does not necessarily list every member of the
305 collection.
307 appCollection element app:collection {
308 attribute next { text } ?,
309 appMember*
310 }
312 o 'app:collection' elements MAY contain any number of 'app:member'
313 elements.
315 o 'app:collection' elements MAY contain a 'next' attribute which
316 identifies a collection document containing member elements
317 updated earlier in time.
319 The members listed in a collection document MUST constitute a
320 consecutive sequence of the collection's members, ordered by their
321 "updated" properties. That is, a collection document MUST contain a
322 contiguous subset of the members of the collection ordered by their
323 'updated' property.
325 5.1.1.2 The 'app:member' Element
327 The 'app:member' represents a single member resource.
329 appMember element app:member {
330 attribute title { text },
331 attribute href { text },
332 attribute hrefreadonly { text } ?,
333 attribute updated { text }
334 }
336 o 'app:member' elements MUST include an 'href' attribute, whose
337 value conveys the URI used to edit the member source
339 o 'app:member' elements MAY include an "hrefreadonly
340 (Section 5.1.1.3)" attribute.
342 o 'app:member' elements MUST include a 'title' attribute, whose
343 value is a human-readable name or description for the item.
345 o 'app:member' elements MUST include an 'updated' attribute, whose
346 value is the 'updated' property of the collection member. Its
347 format MUST conform to the date-time production in [RFC3339].
349 5.1.1.3 The 'hrefreadonly' Attribute
351 This optional attribute identifies a URI which, on a GET request,
352 responds equivalently to how the "href" URI would respond to the same
353 request. Clients SHOULD NOT apply to this URI any HTTP methods that
354 would be expected to modify the state of the resource (e.g. PUT,
355 POST or DELETE). A PUT or POST request to this URI MAY NOT affect
356 the underlying resource. If the "hrefreadonly" attribute is not
357 given, its value defaults to the "href" value. If the "hrefreadonly"
358 attribute is present, and its value is an empty string, then there is
359 no URI that can be treated in the way such a value would be treated.
361 Clients SHOULD use the "href" value to manipulate the resource within
362 the context of the APP itself. Clients SHOULD prefer the
363 "hrefreadonly" value in any other context. For example, if the
364 resource is an image, a client may replace the image data using a PUT
365 on the "href" value, and may even display a preview of the image by
366 fetching the "href" URI. But when creating a public, read-only
367 reference to the same image resource, the client should use the
368 "hrefreadonly" value. If the "hrefreadonly" value is an empty
369 string, the client SHOULD NOT make public reference to the "href"
370 value.
372 [[anchor10: Define extensibility for Collection Documents.]]
374 5.2 Collection Resource
376 This specification defines two HTTP methods for use with collection
377 resources: GET and POST.
379 5.2.1 GET
381 Collections can contain extremely large numbers of resources. A
382 naive client such as a web spider or web browser would be overwhelmed
383 if the response to a GET reflected the full membership of the
384 collection, and the server would waste large amounts of bandwidth and
385 processing time on clients unable to handle the response. As a
386 result, responses to a simple GET request represent a server-
387 determined subset of the collection's membership.
389 In addition, the client MAY send a 'Range' header with a range type
390 of 'udpated', indicating the subset of the collection to be returned.
391 The 'Range' header is described in Section 5.2.4.
393 This specification defines two serializations for Atom Collections.
394 Servers MUST provide both, but MAY also provide additional
395 serializations.
397 1. Atom Collection Documents (application/atomcoll+xml),
398 Section 5.1.
400 2. Atom Collection Documents wrapped by a SOAP envelope
401 (application/soap+xml), .
403 Clients use the HTTP 'Accept' request header to indicate their
404 preference.
406 Example Request, with Accept header
408 GET /collection HTTP/1.1
409 Host: example.org
410 User-Agent: Agent/1.0
411 Accept: application/atomcoll+xml
413 Here, the server could return any subset of the collection as an Atom
414 Collection Document.
416 Example Response, Atom Collection Document
418 HTTP/1.1 200 OK
419 Date: Fri, 25 Mar 2005 17:15:33 GMT
420 Last-Modified: Mon, 04 Oct 2004 18:31:45 GMT
421 ETag: "2b3f6-a4-5b572640"
422 Accept-Ranges: updated
423 Content-Length: nnnn
424 Content-Type: application/atomcoll+xml; charset="utf-8"
426
427
428 ...
429
433 ...
434
436 Example Request, with SOAP Accept header
438 GET /collection HTTP/1.1
439 Host: example.org
440 User-Agent: Cosimo/1.0
441 Accept: application/soap+xml
443 Here, the server could return any subset of the collection as an Atom
444 Feed Document wrapped by a SOAP envelope.
446 Example Response, Atom Feed Document wrapped by a SOAP envelope
448 HTTP/1.1 200 OK
449 Date: Fri, 25 Mar 2005 17:15:33 GMT
450 Last-Modified: Mon, 04 Oct 2004 18:31:45 GMT
451 ETag: "2b3f6-a4-5b572640-89"
452 Accept-Ranges: bytes
453 Content-Length: nnnn
454 Content-Type: application/soap+xml; charset="utf-8"
456
457
458
459
460
461 ...
462
466 ...
467
468
469
471 5.2.2 POST
473 In addition to GET, a Collection Resource also accepts POST requests.
474 The client POSTs a representation of the desired resource to the
475 Collection Resource. Note that some collections only allow members
476 of a specific media-type and a POST MAY generate a response with a
477 status code of 415 ("Unsupported Media Type").
479 In the case of a successful creation, the status code MUST be 201
480 ("Created").
482 Example Request, Create a resource in a collection.
484 POST /collection HTTP/1.1
485 Host: example.org
486 User-Agent: Cosimo/1.0
487 Accept: application/atomcoll+xml
488 Content-Type: image/png
489 Content-Length: nnnn
490 Name: trip-to-beach.png
492 ...binary data...
494 Here, the client is adding a new image resource to a collection. The
495 Name: header indicates the client's desired name for the resource,
496 see Section 5.2.6.
498 Example Response, resource created successfully.
500 HTTP/1.1 201 Created
501 Date: Fri, 25 Mar 2005 17:17:11 GMT
502 Content-Length: nnnn
503 Content-Type: application/atomcoll+xml; charset="utf-8"
504 Location: http://example.org/images/trip-to-the-beach-01.png
506
507
508
512
514 5.2.3 Usage Scenarios
516 These scenarios illustrate common idioms for interactin with
517 Collections.
519 The Atom Collection can be used by clients in two ways. In the first
520 case the client encounters a Collection for the first time and is
521 doing an initial syncronization, that is, retrieving a list of all
522 the members of the collections and possibly retrieving all the
523 members of the collection also. The client can perform a non-partial
524 GET on the collection resource and it will receive a collection
525 document that either contains all the members of the collection, or
526 the collection document root element 'collection' will contain a
527 'next' attribute pointing to the next collection document. By
528 repeatedly following the 'next' attribute from document to document
529 the client can find all the members of the collection.
531 In the second case the client has already done an initial sync, and
532 now needs to re-sync, because the client was just restarted, or some
533 time has passed since a re-sync, etc. The client does a partial GET
534 on the collection document, supplying a Range header that begins from
535 the last time the client sync'd to the current time. The collection
536 document returned will contain only those members of the collection
537 that have changed since the last time the client syncronized.
539 5.2.4 Range: Header
541 HTTP/1.1 allows a client to request that only part (a range of) the
542 collection to be included within the response. HTTP/1.1 uses range
543 units in the Range header field. A collection can be broken down
544 into subranges according to the members 'updated' property. If a
545 Range: header is present in the request, its value explictly
546 identifies the a time interval interval in which all the members
547 'updated' property must fall to be included in the response.
549 Range = "Range" ":" ranges-specifier
551 The value of the Range: header should be a pair of ISO 8601 dates,
552 separated by a slash character; either date may be optionally
553 omitted, in which case the range is understood as stretching to
554 infinity on that end.
556 ranges-specifier = updated-ranges-specifier
557 updated-ranges-specifier = updated-unit "=" updated-range
558 updated-unit = "updated"
559 updated-range = [iso-date] "/" [iso-date]
561 The response to a collection request MUST be a collection document,
562 all of whose 'member' elements fall within the requested range. The
563 request range is considered a closed set, that is, if a 'member'
564 element matches one end of the range exactly it MUST be included in
565 the response. If no members fall in the requested range, the server
566 MUST respond with a collection document containing no 'member'
567 elements.
569 The inclusion of the Range: header in a request changes the request
570 to a "partial GET" [RFC2616].
572 5.2.5 Accept-Ranges: Header
574 The response to a non-partial GET request MUST include an Accept-
575 Ranges header that indicates that the server accepts 'updated' range
576 requests.
578 Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges
579 acceptable-ranges = updated-unit ( 1#range-unit )
581 5.2.6 Name: Header
583 [[anchor13: this is new...]]
585 The POST to a Collection Resource MAY contain a Name: header that
586 indicates the clients suggested name for the resource. The server
587 MAY ignore the Name: header or modify the requested name to suit
588 local conventions.
590 Name = "Name" ":" relative-part
592 The relative-part production is defined in [RFC3986].
594 6. Entry Collection
596 Entry Collections are Collections that restrict their membership to
597 Atom entries. This specification defines two serializations for Atom
598 entries. Servers MUST provide both serializations.
600 1. Atom Entry Documents (application/atom+xml), [AtomFormat].
602 2. Atom Entry Documents wrapped by a SOAP envelope (application/
603 soap+xml), .
605 Clients use the HTTP 'Accept' request header to indicate their
606 preference [RFC2616]. If no 'Accept' header is present in the
607 request, the server is free to choose any serialization. When an
608 HTTP request contains a body, clients MUST include a 'Content-Type'
609 header, and servers MUST accept both application/atom+xml and
610 application/soap+xml message bodies.
612 6.1 Editing Entry Resources
614 Atom entries are edited by sending HTTP requests to an individual
615 entry's URI. Servers can determine the processing necessary to
616 interpret a request by examining the request's HTTP method and
617 'Content-Type' header.
619 If the request method is POST and the 'Content-Type' is application/
620 soap+xml, the SOAP document MUST contain a Web-Method property .
621 This specifcation defines two values for that property, PUT and
622 DELETE.
624 Processing Client Requests
626 +----------------------------------+------+--------+--------+--------+
627 | | GET | PUT | DELETE | POST |
628 +----------------------------------+------+--------+--------+--------+
629 | No Body | Read | x | Delete | x |
630 | | | | | |
631 | Atom Body | x | Update | x | x |
632 | | | | | |
633 | SOAP Body with Web-Method PUT | x | x | x | Update |
634 | | | | | |
635 | SOAP Body with Web-Method DELETE | x | x | x | Delete |
636 +----------------------------------+------+--------+--------+--------+
638 6.2 Role of Atom Entry Elements During Editing
640 The elements of an Atom Entry Document are either a 'Writable
641 Element' or a 'Round Trip Element'.
643 Writable Element - An element of an Atom Entry whose value is
644 editable by the client and not enforced by the server.
646 Round Trip Element - An element of an Atom Entry whose value is
647 enforced by the server and not editable by the client.
649 That categorization will determine the elements' disposition during
650 editing.
652 +--------------------+------------+
653 | Atom Entry Element | Property |
654 +--------------------+------------+
655 | atom:author | Writable |
656 | | |
657 | atom:category | Writable |
658 | | |
659 | atom:content | Writable |
660 | | |
661 | atom:contributor | Writable |
662 | | |
663 | atom:id | Round Trip |
664 | | |
665 | atom:link | Writable |
666 | | |
667 | atom:published | Writable |
668 | | |
669 | atom:source | Writable |
670 | | |
671 | atom:summary | Writable |
672 | | |
673 | atom:title | Writable |
674 | | |
675 | atom:updated | Round Trip |
676 +--------------------+------------+
678 Table 2
680 7. Generic Collection
682 Generic Collections are Collections that do not have uniform
683 restrictions on the representations of the member resources.
685 7.1 Editing Generic Resources
687 Member resources are edited by sending HTTP requests to an individual
688 resource's URI. Servers can determine the processing necessary to
689 interpret a request by examining the request's HTTP method and
690 'Content-Type' header.
692 Processing Client Requests
694 +----------+------+--------+--------+------+
695 | | GET | PUT | DELETE | POST |
696 +----------+------+--------+--------+------+
697 | No Body | Read | x | Delete | x |
698 | | | | | |
699 | Any Body | x | Update | x | x |
700 +----------+------+--------+--------+------+
702 8. Introspection
704 In order for authoring to commence, a client must first discover the
705 capabilities and locations of collections offered.
707 8.1 Introspection Document
709 The Introspection Document describes "workspaces", which are server-
710 defined groupings of collections. There is no requirement that
711 servers support multiple workspaces, and a collection may appear in
712 more than one workspace.
714 The Introspection Document has the media-type 'application/
715 atomserv+xml', see Section 11
717
718
719
720
722
724
725
726
728
730
731
733 8.1.1 Element Definitions
735 8.1.1.1 The 'app:service' Element
737 The "service" element is the document element of a Service Document,
738 acting as a container for service data associated with one or more
739 workspaces.
741 appService element app:service {
742 ( appWorkspace*
743 & anyElement* )
744 }
746 The following child elements are defined by this specification:
748 o app:service elements MAY contain any number of app:workspace
749 elements.
751 8.1.1.2 The 'app:workspace' Element
753 The 'workspace' element element contains information elements about
754 the collections of resources available for editing.
756 appWorkspace element app:workspace {
757 attribute title { text },
758 ( appCollection*
759 & anyElement* )
760 }
762 The following attributes and child elements are defined by this
763 specification:
765 o app:workspace elements MUST contain a 'title' attribute, which
766 conveys a human-readable name for the workspace
768 o app:workspace elements MAY contain any number of app:collection
769 elements.
771 8.1.1.3 The 'app:collection' Element
773 The 'app:collection' element describes collections and their member
774 resources.
776 [[anchor19: We have a collection element that's different than the
777 root element of the collection document. Messy. --R. Sayre]]
779 appCollection element app:collection {
780 attribute title { text },
781 attribute contents { text },
782 attribute href { text },
783 anyElement*
784 }
786 The following attributes are defined by this specification:
788 o app:collection elements MUST contain a 'title' attribute, whose
789 value conveys a human-readable name for the workspace
791 o app:collection elements MAY contain a 'contents' attribute
792 (Section 8.1.1.3.1). If it is not present, it's value is
793 considered to be 'generic'.
795 o app:collection elements MUST contain an 'href' attribute, whose
796 value conveys the URI of the collection.
798 8.1.1.3.1 The 'contents' Attribute
800 The 'contents' attribute conveys the nature of a collection's member
801 resources. This specification defines two initial values for the
802 'contents' attribute:
804 o entry
806 o generic
808 Extensibility for 'content' values is handled [[anchor20: Same as
809 atom:link]].
811 8.1.1.3.1.1 entry
813 A value of 'entry' for the contents attribute indicates that the
814 Collection is an Entry Collection (Section 6).
816 8.1.1.3.1.2 generic
818 A value of 'generic' for the contents attribute indicates that the
819 Collection is a Generic Collection (Section 7).
821 8.2 Introspection Resource
823 To retrieve an Introspection Document, the client sends a GET request
824 to its URI.
826 GET /service-desc HTTP/1.1
827 Host: example.org
828 User-Agent: Cosimo/1.0
829 Accept: application/atomserv+xml
831 The server responds to a GET request by returning an Introspection
832 Document in the message body.
834 HTTP/1.1 200 OK
835 Date: Mon, 21 Mar 2005 19:20:19 GMT
836 Server: CountBasic/2.0
837 Last-Modified: Mon, 21 Mar 2005 19:17:26 GMT
838 ETag: "4c083-268-423f1dc6"
839 Content-Length: nnnn
840 Content-Type: application/atomserv+xml
842
843
844 ...
845
847 8.2.1 Discovery
849 [[anchor24: Add in desc of an HTML link element that points to the
850 Introspection Resource, or add it to the autodisco draft]]
852 9. Securing the Atom Protocol
854 All instances of publishing Atom entries SHOULD be protected by
855 authentication to prevent posting or editing by unknown sources.
856 Atom servers and clients MUST support one of the following
857 authentication mechanisms, and SHOULD support both.
859 o HTTP Digest Authentication [RFC2617]
861 o [@@TBD@@ CGI Authentication ref]
863 Atom servers and clients MAY support encryption of the Atom session
864 using TLS [RFC2246].
866 There are cases where an authentication mechanism may not be
867 required, such as a publicly editable Wiki, or when using the PostURI
868 to post comments to a site that does not require authentication to
869 create comments.
871 9.1 [@@TBD@@ CGI Authentication]
873 This authentication method is included as part of the protocol to
874 allow Atom servers and clients that cannot use HTTP Digest
875 Authentication but where the user can both insert its own HTTP
876 headers and create a CGI program to authenticate entries to the
877 server. This scenario is common in environments where the user
878 cannot control what services the server employs, but the user can
879 write their own HTTP services.
881 10. Security Considerations
883 Because Atom is a publishing protocol, it is important that only
884 authorized users can create and edit entries.
886 The security of Atom is based on HTTP Digest Authentication and/or
887 [@@TBD@@ CGI Authentication]. Any weaknesses in either of these
888 authentication schemes will obviously affect the security of the Atom
889 Publishing Protocol.
891 Both HTTP Digest Authentication and [@@TBD@@ CGI Authentication] are
892 susceptible to dictionary-based attacks on the shared secret. If the
893 shared secret is a password (instead of a random string with
894 sufficient entropy), an attacker can determine the secret by
895 exhaustively comparing the authenticating string with hashed results
896 of the public string and dictionary entries.
898 See RFC 2617 for more detailed description of the security properties
899 of HTTP Digest Authentication.
901 @@TBD@@ Talk here about using HTTP basic and digest authentication.
903 @@TBD@@ Talk here about denial of service attacks using large XML
904 files, or the billion laughs DTD attack.
906 11. IANA Considerations
908 A Atom Collection Document, when serialized as XML 1.0, can be
909 identified with the following media type:
911 MIME media type name: application
913 MIME subtype name: atomcoll+xml
915 Mandatory parameters: None.
917 Optional parameters:
919 "charset": This parameter has identical semantics to the charset
920 parameter of the "application/xml" media type as specified in
921 [RFC3023].
923 Encoding considerations: Identical to those of "application/xml" as
924 described in [RFC3023], section 3.2.
926 Security considerations: As defined in this specification.
927 [[anchor28: update upon publication]]
929 In addition, as this media type uses the "+xml" convention, it
930 shares the same security considerations as described in [RFC3023],
931 section 10.
933 Interoperability considerations: There are no known interoperability
934 issues.
936 Published specification: This specification. [[anchor29: update upon
937 publication]]
939 Applications that use this media type: No known applications
940 currently use this media type.
942 Additional information:
944 Magic number(s): As specified for "application/xml" in [RFC3023],
945 section 3.2.
947 File extension: .atomcoll
949 Fragment identifiers: As specified for "application/xml" in
950 [RFC3023], section 5.
952 Base URI: As specified in [RFC3023], section 6.
954 Macintosh File Type code: TEXT
956 Person and email address to contact for further information: Joe
957 Gregorio
959 Intended usage: COMMON
961 Author/Change controller: IESG
963 An Atom Introspection Document, when serialized as XML 1.0, can be
964 identified with the following media type:
966 MIME media type name: application
968 MIME subtype name: atomserv+xml
970 Mandatory parameters: None.
972 Optional parameters:
974 "charset": This parameter has identical semantics to the charset
975 parameter of the "application/xml" media type as specified in
976 [RFC3023].
978 Encoding considerations: Identical to those of "application/xml" as
979 described in [RFC3023], section 3.2.
981 Security considerations: As defined in this specification.
982 [[anchor30: update upon publication]]
984 In addition, as this media type uses the "+xml" convention, it
985 shares the same security considerations as described in [RFC3023],
986 section 10.
988 Interoperability considerations: There are no known interoperability
989 issues.
991 Published specification: This specification. [[anchor31: update upon
992 publication]]
994 Applications that use this media type: No known applications
995 currently use this media type.
997 Additional information:
999 Magic number(s): As specified for "application/xml" in [RFC3023],
1000 section 3.2.
1002 File extension: .atomsrv
1004 Fragment identifiers: As specified for "application/xml" in
1005 [RFC3023], section 5.
1007 Base URI: As specified in [RFC3023], section 6.
1009 Macintosh File Type code: TEXT
1011 Person and email address to contact for further information: Joe
1012 Gregorio
1014 Intended usage: COMMON
1016 Author/Change controller: This specification's author(s). [[anchor32:
1017 update upon publication]]
1019 12. References
1021 12.1 Normative References
1023 [AtomFormat]
1024 Nottingham, M. and R. Sayre, "The Atom Syndication
1025 Format", work-in-progress, April 2005.
1027 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1028 Requirement Levels", BCP 14, RFC 2119, March 1997.
1030 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
1031 RFC 2246, January 1999.
1033 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
1034 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
1035 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
1037 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
1038 Leach, P., Luotonen, A., and L. Stewart, "HTTP
1039 Authentication: Basic and Digest Access Authentication",
1040 RFC 2617, June 1999.
1042 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media
1043 Types", RFC 3023, January 2001.
1045 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
1046 Timestamps", RFC 3339, July 2002.
1048 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
1049 Resource Identifier (URI): Generic Syntax", STD 66,
1050 RFC 3986, January 2005.
1052 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
1053 Identifiers (IRIs)", RFC 3987, January 2005.
1055 [W3C.REC-soap12-part1-20030624]
1056 Nielsen, H., Mendelsohn, N., Gudgin, M., Hadley, M., and
1057 J. Moreau, "SOAP Version 1.2 Part 1: Messaging Framework",
1058 W3C REC REC-soap12-part1-20030624, June 2003.
1060 [W3C.REC-soap12-part2-20030624]
1061 Nielsen, H., Hadley, M., Moreau, J., Mendelsohn, N., and
1062 M. Gudgin, "SOAP Version 1.2 Part 2: Adjuncts", W3C
1063 REC REC-soap12-part2-20030624, June 2003.
1065 [W3C.REC-xml-20040204]
1066 Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T.,
1067 and E. Maler, "Extensible Markup Language (XML) 1.0 (Third
1068 Edition)", W3C REC REC-xml-20040204, February 2004.
1070 12.2 Informative References
1072 [W3C.REC-webarch-20041215]
1073 Walsh, N. and I. Jacobs, "Architecture of the World Wide
1074 Web, Volume One", W3C REC REC-webarch-20041215,
1075 December 2004.
1077 URIs
1079 [1]
1081 Authors' Addresses
1083 Joe Gregorio (editor)
1084 BitWorking, Inc
1085 1002 Heathwood Dairy Rd.
1086 Apex, NC 27502
1087 US
1089 Phone: +1 919 272 3764
1090 Email: joe@bitworking.com
1091 URI: http://bitworking.com/
1093 Robert Sayre (editor)
1095 Email: rfsayre@boswijck.com
1096 URI: http://boswijck.com
1098 Appendix A. Revision History
1100 draft-ietf-atompub-protocol-04 - Add ladder diagrams, reorganize, add
1101 SOAP interactions
1103 draft-ietf-atompub-protocol-03 - Incorporates PaceSliceAndDice3 and
1104 PaceIntrospection.
1106 draft-ietf-atompub-protocol-02 - Incorporates Pace409Response,
1107 PacePostLocationMust, and PaceSimpleResourcePosting.
1109 draft-ietf-atompub-protocol-01 - Added in sections on Responses for
1110 the EditURI. Allow 2xx for response to EditURI PUTs. Elided all
1111 mentions of WSSE. Started adding in some normative references.
1112 Added the section "Securing the Atom Protocol". Clarified that it is
1113 possible that the PostURI and FeedURI could be the same URI. Cleaned
1114 up descriptions for Response codes 400 and 500.
1116 Rev draft-ietf-atompub-protocol-00 - 5Jul2004 - Renamed the file and
1117 re-titled the document to conform to IETF submission guidelines.
1118 Changed MIME type to match the one selected for the Atom format.
1119 Numerous typographical fixes. We used to have two 'Introduction'
1120 sections. One of them was moved into the Abstract the other absorbed
1121 the Scope section. IPR and copyright notifications were added.
1123 Rev 09 - 10Dec2003 - Added the section on SOAP enabled clients and
1124 servers.
1126 Rev 08 - 01Dec2003 - Refactored the specification, merging the
1127 Introspection file into the feed format. Also dropped the
1128 distinction between the type of URI used to create new entries and
1129 the kind used to create comments. Dropped user preferences.
1131 Rev 07 - 06Aug2003 - Removed the use of the RSD file for auto-
1132 discovery. Changed copyright until a final standards body is chosen.
1133 Changed query parameters for the search facet to all begin with atom-
1134 to avoid name collisions. Updated all the Entries to follow the 0.2
1135 version. Changed the format of the search results and template file
1136 to a pure element based syntax.
1138 Rev 06 - 24Jul2003 - Moved to PUT for updating Entries. Changed all
1139 the mime-types to application/x.atom+xml. Added template editing.
1140 Changed 'edit-entry' to 'create-entry' in the Introspection file to
1141 more accurately reflect it's purpose.
1143 Rev 05 - 17Jul2003 - Renamed everything Echo into Atom. Added
1144 version numbers in the Revision history. Changed all the mime-types
1145 to application/atom+xml.
1147 Rev 04 - 15Jul2003 - Updated the RSD version used from 0.7 to 1.0.
1148 Change the method of deleting an Entry from POSTing to
1149 using the HTTP DELETE verb. Also changed the query interface to GET
1150 instead of POST. Moved Introspection Discovery to be up under
1151 Introspection. Introduced the term 'facet' for the services listed
1152 in the Introspection file.
1154 Rev 03 - 10Jul2003 - Added a link to the Wiki near the front of the
1155 document. Added a section on finding an Entry. Retrieving an Entry
1156 now broken out into it's own section. Changed the HTTP status code
1157 for a successful editing of an Entry to 205.
1159 Rev 02 - 7Jul2003 - Entries are no longer returned from POSTs,
1160 instead they are retrieved via GET. Cleaned up figure titles, as
1161 they are rendered poorly in HTML. All content-types have been
1162 changed to application/atom+xml.
1164 Rev 01 - 5Jul2003 - Renamed from EchoAPI.html to follow the more
1165 commonly used format: draft-gregorio-NN.html. Renamed all references
1166 to URL to URI. Broke out introspection into it's own section. Added
1167 the Revision History section. Added more to the warning that the
1168 example URIs are not normative.
1170 Intellectual Property Statement
1172 The IETF takes no position regarding the validity or scope of any
1173 Intellectual Property Rights or other rights that might be claimed to
1174 pertain to the implementation or use of the technology described in
1175 this document or the extent to which any license under such rights
1176 might or might not be available; nor does it represent that it has
1177 made any independent effort to identify any such rights. Information
1178 on the procedures with respect to rights in RFC documents can be
1179 found in BCP 78 and BCP 79.
1181 Copies of IPR disclosures made to the IETF Secretariat and any
1182 assurances of licenses to be made available, or the result of an
1183 attempt made to obtain a general license or permission for the use of
1184 such proprietary rights by implementers or users of this
1185 specification can be obtained from the IETF on-line IPR repository at
1186 http://www.ietf.org/ipr.
1188 The IETF invites any interested party to bring to its attention any
1189 copyrights, patents or patent applications, or other proprietary
1190 rights that may cover technology that may be required to implement
1191 this standard. Please address the information to the IETF at
1192 ietf-ipr@ietf.org.
1194 The IETF has been notified of intellectual property rights claimed in
1195 regard to some or all of the specification contained in this
1196 document. For more information consult the online list of claimed
1197 rights.
1199 Disclaimer of Validity
1201 This document and the information contained herein are provided on an
1202 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
1203 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
1204 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
1205 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
1206 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1207 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1209 Copyright Statement
1211 Copyright (C) The Internet Society (2005). This document is subject
1212 to the rights, licenses and restrictions contained in BCP 78, and
1213 except as set forth therein, the authors retain all their rights.
1215 Acknowledgment
1217 Funding for the RFC Editor function is currently provided by the
1218 Internet Society.