idnits 2.17.1
draft-sayre-atompub-protocol-basic-06.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 621.
-- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 598.
-- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 605.
-- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 611.
** 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 document seems to lack a both a reference to RFC 2119 and the
recommended RFC 2119 boilerplate, even if it appears to use RFC 2119
keywords.
RFC 2119 keyword, line 430: '...iption documents MUST be well-formed X...'
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the RFC 3978 Section 5.4 Copyright Line does not
match the current year
-- 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 (January 24, 2006) is 6666 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)
-- Missing reference section? 'RFC2616' on line 64 looks like a reference
-- Missing reference section? 'RFC3986' on line 459 looks like a reference
-- Missing reference section? 'RFC3987' on line 458 looks like a reference
-- Missing reference section? 'AtomFormat' on line 79 looks like a reference
-- Missing reference section? 'RFC2045' on line 328 looks like a reference
Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 12 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Atompub Working Group R. Sayre
3 Internet-Draft January 24, 2006
4 Expires: July 28, 2006
6 The Atom Publishing Protocol (Basic)
7 draft-sayre-atompub-protocol-basic-06
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 July 28, 2006.
34 Copyright Notice
36 Copyright (C) The Internet Society (2006).
38 Abstract
40 This memo presents a protocol that uses XML and HTTP to publish and
41 edit Web resources.
43 Table of Contents
45 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
46 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3
47 3. The Atom Publishing Protocol Model . . . . . . . . . . . . . . 3
48 4. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 3
49 5. Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
50 6. Authoring . . . . . . . . . . . . . . . . . . . . . . . . . . 4
51 7. Atom Protocol Feeds . . . . . . . . . . . . . . . . . . . . . 6
52 8. Media Feeds . . . . . . . . . . . . . . . . . . . . . . . . . 8
53 9. Service Description . . . . . . . . . . . . . . . . . . . . . 10
54 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
55 11. Security Considerations . . . . . . . . . . . . . . . . . . . 14
56 12. Informative References . . . . . . . . . . . . . . . . . . . . 15
57 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15
58 Appendix B. Change History . . . . . . . . . . . . . . . . . . . 15
59 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16
60 Intellectual Property and Copyright Statements . . . . . . . . . . 17
62 1. Introduction
64 The Atom Publishing Protocol uses HTTP [RFC2616] and XML [W3C.REC-
65 xml-20040204] to publish and edit Web resources.
67 2. Notational Conventions
69 The Atom Protocol namespace is "http://purl.org/atom/app#". This
70 specification refers to it by using the prefix "pub", but that prefix
71 is arbitrary.
73 The terms 'URI' and 'IRI' are shorthand for the identifiers specified
74 in [RFC3986] and [RFC3987].
76 3. The Atom Publishing Protocol Model
78 The Atom Protocol uses HTTP to operate on collections of Web
79 resources represented by Atom feeds [AtomFormat]. This section
80 illustrates the editing cycle for Atom entries.
81 o GET is used to retrieve a representation of a resource or perform
82 a read-only query.
83 o POST is used to create a new, dynamically-named resource.
84 o PUT is used to update a known resource.
85 o DELETE is used to remove a resource.
87 4. Discovery
89 To discover the location of the feeds exposed by an Atom Protocol
90 service, the client must locate and request a Service Description
91 Document (Section 6).
93 Client Server
94 | |
95 | 1.) GET Service URI |
96 |------------------------------->|
97 | |
98 | 2.) Service Description Doc |
99 |<-------------------------------|
100 | |
102 1. The client sends a GET request to the Service Description URI.
104 2. The server responds with a Service Description Document
105 containing the locations of feeds provided by the service. The
106 content of this document can vary based on aspects of the client
107 request, including, but not limited to, authentication
108 credentials.
110 5. Listing
112 Once the client has discovered the location of a feed in the outline,
113 it can request a listing of the feed's entries. However, a feed
114 might contain an extremely large number of entries, so servers are
115 likely to list a small subset of them by default.
117 Client Server
118 | |
119 | 1.) GET to Atom Feed URI |
120 |------------------------------->|
121 | |
122 | 2.) 200 OK, Atom Feed Doc |
123 |<-------------------------------|
124 | |
126 1. The client sends a GET request to the Atom Feed's URI.
127 2. The server responds with an Atom Feed Document containing a full
128 or partial listing of the feed's membership.
130 6. Authoring
132 After locating a feed, a client can add entries by sending a POST
133 request to the feed; other changes are accomplished by sending HTTP
134 requests to each entry.
136 6.1. Create
138 Client Server
139 | |
140 | 1.) POST Entry to Feed URI |
141 |------------------------------->|
142 | |
143 | 2.) 201 Created @ Location |
144 |<-------------------------------|
145 | |
147 1. The client sends an Atom Entry to the server via HTTP POST. The
148 Request URI is that of the Atom Feed.
149 2. The server responds with a response of "201 Created" and a
150 "Location" header containing the URI of the newly-created Atom
151 Entry.
153 6.2. Read
155 Client Server
156 | |
157 | 1.) GET or HEAD to Entry URI |
158 |------------------------------->|
159 | |
160 | 2.) 200 OK Atom Entry |
161 |<-------------------------------|
162 | |
164 1. The client sends a GET (or HEAD) request to the entry's URI.
165 2. The server responds with an Atom Entry document.
167 6.3. Update
169 Client Server
170 | |
171 | 1.) PUT to Entry URI |
172 |------------------------------->|
173 | |
174 | 2.) 200 OK |
175 |<-------------------------------|
176 | |
178 1. The client PUTs an updated Atom Entry Document to the entry's
179 URI.
180 2. The server responds with a successful status code.
182 6.4. Delete
184 Client Server
185 | |
186 | 1.) DELETE to Entry URI |
187 |------------------------------->|
188 | |
189 | 2.) 204 No Content |
190 |<-------------------------------|
191 | |
193 1. The client sends a DELETE request to the entry's URI.
194 2. The server responds with successful status code.
196 6.5. Success and Failure
198 HTTP defines classes of response. HTTP status codes of the form 2xx
199 signal that a request was successful. HTTP status codes of the form
200 4xx or 5xx signal that an error has occurred, and the request has
201 failed. Consult the HTTP specification for more detailed definitions
202 of each status code.
204 7. Atom Protocol Feeds
206 7.1. GET
208 Feeds can contain extremely large numbers of resources. A naive
209 client such as a web spider or web browser would be overwhelmed if
210 the response to a GET contained every entry in the feed, and the
211 server would waste large amounts of bandwidth and processing time on
212 clients unable to handle the response. As a result, responses to a
213 simple GET request represent a server-determined subset of the
214 entries in the feed.
216 An example Atom Protocol feed:
218
220 My Posts1
221 urn:uuid:ce61592c-14e2-4557-978e-dfbd444aefa6
222 2005-12-21T04:11:00-08:00
223
224
225 title 25
226 2005-12-21T04:11:00-08:00
227
228 Foo
229
230 It started out looking simple enough...
231 urn:uuid:941e12b4-6eeb-4753-959d-0cbc51875387
232
233
234
235 ...
236
238 Each member entry is represented by an atom:entry element, but those
239 entries are not an editable representation of the entry. To retrieve
240 the source representation of the entry, clients send a GET request to
241 the URI found in each entry's pub:edit element (see Section 4.3.1).
242 Derived resources are located by examining an entry's atom:link
243 elements.
245 7.2. POST
247 An Atom Protocol feed also accepts POST requests. The client POSTs a
248 representation of the desired resource to the APP feed. Some feeds
249 only accept POST requests with certain media-types, so a POST request
250 could result in a response with a status code of 415 ("Unsupported
251 Media Type"). In the case of a successful creation, the status code
252 is 201 ("Created").
254 Example request creating a new entry in a feed:
256 POST /collection HTTP/1.1
257 Host: example.org
258 User-Agent: Cosimo/1.0
259 Content-Type: application/atom+xml
260 Content-Length: nnnn
262 ...data...
264 Example response.
266 HTTP/1.1 201 Created
267 Date: Mon, 21 Mar 2005 19:20:19 GMT
268 Server: CountBasic/2.0
269 ETag: "4c083-268-423f1dc6"
270 Location: http://example.org/stuff/foo13241234.atom
272 8. Media Feeds
274 The entries within Media Feeds do not represent uniform types of
275 content. For example, they might contain JPEG images, text
276 documents, MPEG movies, or any other type of resource the server
277 allows.
279 8.1. GET
281 Media Feeds return an Atom feed much like the textual Atom Protcol
282 feeds described above, but with a few additions. The entries also
283 contain an atom:content element with a 'src' attribute pointing to
284 the media resource. This URI can be used to edit the uploaded media
285 resource, using PUT and DELETE. Such entries may contain edit links
286 used to edit the entry metadata. As with any Atom entry, related and
287 derived resources can be located by inspecting an entry's atom:link
288 elements.
290 An example Media Feed:
292
294 My Posts1
295
296 Foo
297
298 urn:uuid:ce61592c-14e2-4557-978e-dfbd444aefa6
299 2005-12-21T04:11:00-08:00
300
301
302 Title25
303 2005-12-21T04:11:00-08:00
304 urn:uuid:941e12b4-6eeb-4753-959d-0cbc51875387
305
306
308 This was awesome.
309
310
311 ...
312
314 The Atom Syndication Format requires that each such entry contain an
315 atom:title and atom:summary element. This requirement can be
316 challenging to meet without requiring users to enter tedious
317 metadata, but servers should attempt to provide textual data about
318 the resource in the interests of accessibility. The atom:title
319 element will likely be provided by the client, as a way for users to
320 associate their local resources with those they have uploaded to the
321 server (see POST below).
323 8.2. POST
325 To add an entry to a Media Feed, clients POST the resource to the
326 Media Feed's URI. Clients should provide a 'Title' request header to
327 provide the server with a short string identifying the resource to
328 users. Clients may include a 'Content-Description' header [RFC2045]
329 providing a more complete description of the content. In addition,
330 servers may inspect the POSTed entity for additional metadata to be
331 exposed in an atom:entry element when listed in a Media Feed. For
332 example, the server might inspect a JPEG file for EXIF headers
333 containing creator data.
335 An example request:
337 POST /collection HTTP/1.1
338 Host: example.org
339 User-Agent: Cosimo/1.0
340 Content-Type: image/tiff
341 Content-Length: nnnn
342 Title: A Trip to the beach
343 Content-Description: It was so fun.
345 ...binary data...
347 An example response:
349 HTTP/1.1 201 Created
350 Date: Mon, 21 Mar 2005 19:20:19 GMT
351 Server: CountBasic/2.0
352 ETag: "4c083-268-423f1dc6"
353 Location: http://example.org/stuff/beach.tiff
355 [@@ deal with response ambiguity noted in WG]
357 9. Service Description
359 Many Atom Protocol applications require a basic resource layout in
360 order to ease configuration requirements. Servers use Service
361 Description documents to convey information about related groups of
362 Atom Protocol feeds. On a blogging service, for example, each group
363 might represent a distinct blog and associated resources.
365 Example Service Description document:
367
368
370
372
374
375
378
380 Servers are not required to expose a Service Description document,
381 but experimental deployment experience has shown that a single
382 document which signals some basic information about the server's
383 configuration can greatly simplify client implementations. The
384 simplest useful Service Description document shows the location of a
385 single resource:
387
388
390
392 If another service is added, the document can be upgraded to reflect
393 new resources.
395
396
398
400
402 Finally, more extensive services could require some amount of
403 hierarchical grouping.
405
406
408
410
411
412
414
416
417
419 This example shows that links to APP feeds can appear in
420 elements used to group other resources. The element named
421 "Other Things" does not contain an 'href' attribute, so it functions
422 as a simple named group of the services it contains.
424 9.1. Categories
426 [@@ tbd]
428 9.2. Document Format
430 Service Description documents MUST be well-formed XML [W3C.REC-xml-
431 20040204].
433 The root element of an APP Service Description Document is "".
434 This specification does not define any attributes of the
435 element, but the element can have any number of attributes.
437 Zero or more elements appear as child elements of .
438 Also, elements may contain zero or more elements.
439 This specification defines three attributes of the element.
440 elements contain at least a 'name' or 'href' attribute.
441 Additional service properties too large or structured to include in
442 attribute values could appear as child elements of the service
443 element.
445 elements can contain any number of elements that are not
446 elements, and elements can contain any number of
447 elements that are not elements.
449 9.2.1. The 'name' Attribute
451 The 'name' attribute contains a short string describing the service
452 element. Entities such as "&" and "<" represent their
453 corresponding characters ("&" and "<" respectively), not markup.
455 9.2.2. The 'href' Attribute
457 The 'href' attribute contains an IRI reference interpreted relative
458 to the in-scope base IRI [RFC3987]. Most protocols require URIs
459 [RFC3986], so IRIs usually need to be converted to URIs before being
460 dereferenced.
462 9.2.3. The 'class' Attribute
464 The 'class' attribute contains a space-separated list of strings used
465 to classify the service element. This specification defines two
466 values for the 'class' attribute:
468 o feed
469 o media feed
471 These values correspond to standard feeds and media feeds,
472 respectively. If the 'class' attribute is not present, the
473 element can be processed as if the attribute were present with a
474 value of 'feed'.
476 9.2.4. Relax NG Schema
478 Service Description documents conform to the schema below.
480 default namespace = "http://purl.org/atom/app#"
481 start = app
483 app = element app {
484 anyAttribute*,
485 (service* & anyElement*)
486 }
488 service = element service {
489 (nameAtt | hrefAtt), anyAttribute*,
490 (service* & anyElement*)
491 }
493 nameAtt = attribute name { text }
494 hrefAtt = attribute href { text }
495 classAtt = attribute class { text }
497 anyElement = element * { (anyAttribute | text | anyElement)* }
498 anyAttribute = attribute * { text }
500 9.2.5. Extending Service Description
502 The Service Description document format can be freely extended by
503 adding attributes and elements not defined by this specification.
505 Valid Service Description document with extensions:
507
508 42
509
510 hmm
511
512
514 Additional service properties too large or structured to include in
515 attribute values could appear as child elements of the or
516 elements. elements may contain any number of elements
517 that are not elements, and elements may contain
518 any number of elements that are not elements.
520 9.2.6. User Agent Conformance
522 Foreign markup is markup not defined by this specification.
524 Software consuming Service Description documents must not halt
525 processing when any foreign markup is encountered. Software may
526 ignore the markup and process any content of foreign elements as
527 though the surrounding markup were not present. For example,
528 software may process
530
531
532
534
536
537
538 ...
539
540
541
542
544 as though the and elements were not present.
546 Software conforming to this specification may halt processing when
547 documents that do not conform to the schema are encountered.
549 10. IANA Considerations
551 [@@ fill out in for application/sd+xml (service description)]
553 11. Security Considerations
554 12. Informative References
556 Appendix A. Acknowledgements
558 This draft is a variant of the in-progress Atom Publishing Protocol
559 specification from the IETF Atompub WG, and owes a debt to the WG's
560 members.
562 Appendix B. Change History
563 -06: Change service description format.
564 Change IPR terms to full3978
565 -interlude: More unproductive WG thrashing.
566 -05: Death to collections!
567 Switch APPO instead of XOXO.
568 State the obvious about the extension elements.
569 Remove RFC2119 reference.
570 Change "Normative References" to "References".
571 -04: Add pub:control element.
572 Reword collection POST.
573 Prophesize about atom:id.
574 -03: Remove search/query capabilities added in -02 Drop round-
575 tripping. Most of them were writable, some folks wanted to edit
576 atom:updated, that leaves atom:id, and that seems foolish to try
577 and edit, so go ahead and try it if you think you can.
578 -02: Add search/query capabilities.
579 -01: Split from WG draft, cut SOAP, and much other cruft.
580 -interlude: Becomes WG draft.
581 -00: Split from WG draft.
583 Author's Address
585 Robert Sayre
587 Email: rfsayre@boswijck.com
589 Intellectual Property Statement
591 The IETF takes no position regarding the validity or scope of any
592 Intellectual Property Rights or other rights that might be claimed to
593 pertain to the implementation or use of the technology described in
594 this document or the extent to which any license under such rights
595 might or might not be available; nor does it represent that it has
596 made any independent effort to identify any such rights. Information
597 on the procedures with respect to rights in RFC documents can be
598 found in BCP 78 and BCP 79.
600 Copies of IPR disclosures made to the IETF Secretariat and any
601 assurances of licenses to be made available, or the result of an
602 attempt made to obtain a general license or permission for the use of
603 such proprietary rights by implementers or users of this
604 specification can be obtained from the IETF on-line IPR repository at
605 http://www.ietf.org/ipr.
607 The IETF invites any interested party to bring to its attention any
608 copyrights, patents or patent applications, or other proprietary
609 rights that may cover technology that may be required to implement
610 this standard. Please address the information to the IETF at
611 ietf-ipr@ietf.org.
613 Disclaimer of Validity
615 This document and the information contained herein are provided on an
616 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
617 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
618 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
619 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
620 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
621 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
623 Copyright Statement
625 Copyright (C) The Internet Society (2006). This document is subject
626 to the rights, licenses and restrictions contained in BCP 78, and
627 except as set forth therein, the authors retain all their rights.
629 Acknowledgment
631 Funding for the RFC Editor function is currently provided by the
632 Internet Society.