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.