Changeset 1923 for draft-ietf-httpbis/latest/p2-semantics.xml
- Timestamp:
- 01/10/12 07:39:45 (10 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
draft-ietf-httpbis/latest/p2-semantics.xml
r1922 r1923 289 289 </t> 290 290 291 <section title="Representation Header Fields" anchor="representation.header.fields">291 <section title="Representation Metadata" anchor="representation.metadata"> 292 292 <x:anchor-alias value="representation-header"/> 293 293 <t> … … 300 300 </t> 301 301 <t> 302 The following header fields are defined asrepresentation metadata:302 The following header fields are defined to convey representation metadata: 303 303 </t> 304 304 <texttable align="left"> … … 312 312 <c>Expires</c> <c>&header-expires;</c> 313 313 </texttable> 314 315 <section title="Data Type" anchor="data.type"> 316 317 <section title="Media Types" anchor="media.types"> 318 <x:anchor-alias value="media-type"/> 319 <x:anchor-alias value="type"/> 320 <x:anchor-alias value="subtype"/> 321 <t> 322 HTTP uses Internet Media Types <xref target="RFC2046"/> in the 323 <x:ref>Content-Type</x:ref> (<xref target="header.content-type"/>) 324 and <x:ref>Accept</x:ref> (<xref target="header.accept"/>) header fields in 325 order to provide open and extensible data typing and type negotiation. 326 </t> 327 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="media-type"/><iref primary="true" item="Grammar" subitem="type"/><iref primary="true" item="Grammar" subitem="subtype"/> 328 <x:ref>media-type</x:ref> = <x:ref>type</x:ref> "/" <x:ref>subtype</x:ref> *( <x:ref>OWS</x:ref> ";" <x:ref>OWS</x:ref> <x:ref>parameter</x:ref> ) 329 <x:ref>type</x:ref> = <x:ref>token</x:ref> 330 <x:ref>subtype</x:ref> = <x:ref>token</x:ref> 331 </artwork></figure> 332 <t anchor="rule.parameter"> 333 <x:anchor-alias value="attribute"/> 334 <x:anchor-alias value="parameter"/> 335 <x:anchor-alias value="value"/> 336 The type/subtype &MAY; be followed by parameters in the form of 337 attribute/value pairs. 338 </t> 339 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="parameter"/><iref primary="true" item="Grammar" subitem="attribute"/><iref primary="true" item="Grammar" subitem="value"/> 340 <x:ref>parameter</x:ref> = <x:ref>attribute</x:ref> "=" <x:ref>value</x:ref> 341 <x:ref>attribute</x:ref> = <x:ref>token</x:ref> 342 <x:ref>value</x:ref> = <x:ref>word</x:ref> 343 </artwork></figure> 344 <t> 345 The type, subtype, and parameter attribute names are case-insensitive. 346 Parameter values might or might not be case-sensitive, depending on the 347 semantics of the parameter name. The presence or absence of a parameter might 348 be significant to the processing of a media-type, depending on its 349 definition within the media type registry. 350 </t> 351 <t> 352 A parameter value that matches the <x:ref>token</x:ref> production can be 353 transmitted as either a token or within a quoted-string. The quoted and 354 unquoted values are equivalent. 355 </t> 356 <t> 357 Media-type values are registered with the Internet Assigned Number 358 Authority (IANA). The media type registration process is 359 outlined in <xref target="RFC4288"/>. Use of non-registered media types is 360 discouraged. 361 </t> 362 </section> 363 364 <section title="Character Encodings (charset)" anchor="character.sets"> 365 <t> 366 HTTP uses charset names to indicate the character encoding of a 367 textual representation. 368 </t> 369 <t anchor="rule.charset"> 370 <x:anchor-alias value="charset"/> 371 A character encoding is identified by a case-insensitive token. The 372 complete set of tokens is defined by the IANA Character Set registry 373 (<eref target="http://www.iana.org/assignments/character-sets"/>). 374 </t> 375 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="charset"/> 376 <x:ref>charset</x:ref> = <x:ref>token</x:ref> 377 </artwork></figure> 378 <t> 379 Although HTTP allows an arbitrary token to be used as a charset 380 value, any token that has a predefined value within the IANA 381 Character Set registry &MUST; represent the character encoding defined 382 by that registry. Applications &SHOULD; limit their use of character 383 encodings to those defined within the IANA registry. 384 </t> 385 <t> 386 HTTP uses charset in two contexts: within an <x:ref>Accept-Charset</x:ref> 387 request header field (in which the charset value is an unquoted token) and 388 as the value of a parameter in a <x:ref>Content-Type</x:ref> header field 389 (within a request or response), in which case the parameter value of the 390 charset parameter can be quoted. 391 </t> 392 <t> 393 Implementers need to be aware of IETF character set requirements <xref target="RFC3629"/> 394 <xref target="RFC2277"/>. 395 </t> 396 </section> 397 398 <section title="Canonicalization and Text Defaults" anchor="canonicalization.and.text.defaults"> 399 <t> 400 Internet media types are registered with a canonical form. A 401 representation transferred via HTTP messages &MUST; be in the 402 appropriate canonical form prior to its transmission except for 403 "text" types, as defined in the next paragraph. 404 </t> 405 <t> 406 When in canonical form, media subtypes of the "text" type use CRLF as 407 the text line break. HTTP relaxes this requirement and allows the 408 transport of text media with plain CR or LF alone representing a line 409 break when it is done consistently for an entire representation. HTTP 410 applications &MUST; accept CRLF, bare CR, and bare LF as indicating 411 a line break in text media received via HTTP. In 412 addition, if the text is in a character encoding that does not 413 use octets 13 and 10 for CR and LF respectively, as is the case for 414 some multi-byte character encodings, HTTP allows the use of whatever octet 415 sequences are defined by that character encoding to represent the 416 equivalent of CR and LF for line breaks. This flexibility regarding 417 line breaks applies only to text media in the payload body; a bare CR 418 or LF &MUST-NOT; be substituted for CRLF within any of the HTTP control 419 structures (such as header fields and multipart boundaries). 420 </t> 421 <t> 422 If a representation is encoded with a content-coding, the underlying 423 data &MUST; be in a form defined above prior to being encoded. 424 </t> 425 </section> 426 427 <section title="Multipart Types" anchor="multipart.types"> 428 <t> 429 MIME provides for a number of "multipart" types — encapsulations of 430 one or more representations within a single message body. All multipart 431 types share a common syntax, as defined in <xref target="RFC2046" x:sec="5.1.1" x:fmt="of"/>, 432 and include a boundary parameter as part of the media type 433 value. The message body is itself a protocol element; a sender &MUST; 434 generate only CRLF to represent line breaks between body-parts. 435 </t> 436 <t> 437 In general, HTTP treats a multipart message body no differently than 438 any other media type: strictly as payload. HTTP does not use the 439 multipart boundary as an indicator of message body length. 440 <!-- jre: re-insert removed text pointing to caching? --> 441 In all other respects, an HTTP user agent &SHOULD; follow the same or similar 442 behavior as a MIME user agent would upon receipt of a multipart type. 443 The MIME header fields within each body-part of a multipart message body 444 do not have any significance to HTTP beyond that defined by 445 their MIME semantics. 446 </t> 447 <t> 448 A recipient &MUST; treat an unrecognized multipart subtype 449 as being equivalent to "multipart/mixed". 450 </t> 451 <x:note> 452 <t> 453 &Note; The "multipart/form-data" type has been specifically defined 454 for carrying form data suitable for processing via the POST 455 request method, as described in <xref target="RFC2388"/>. 456 </t> 457 </x:note> 458 </section> 314 459 315 460 <section title="Content-Type" anchor="header.content-type"> … … 353 498 processing semantics. Implementers are encouraged to provide a means of 354 499 disabling such "content sniffing" when it is used. 500 </t> 501 </section> 502 </section> 503 504 <section title="Data Encoding" anchor="data.encoding"> 505 506 <section title="Content Codings" anchor="content.codings"> 507 <x:anchor-alias value="content-coding"/> 508 <t> 509 Content coding values indicate an encoding transformation that has 510 been or can be applied to a representation. Content codings are primarily 511 used to allow a representation to be compressed or otherwise usefully 512 transformed without losing the identity of its underlying media type 513 and without loss of information. Frequently, the representation is stored in 514 coded form, transmitted directly, and only decoded by the recipient. 515 </t> 516 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="content-coding"/> 517 <x:ref>content-coding</x:ref> = <x:ref>token</x:ref> 518 </artwork></figure> 519 <t> 520 All content-coding values are case-insensitive. HTTP/1.1 uses 521 content-coding values in the <x:ref>Accept-Encoding</x:ref> 522 (<xref target="header.accept-encoding"/>) and <x:ref>Content-Encoding</x:ref> 523 (<xref target="header.content-encoding"/>) header fields. Although the value 524 describes the content-coding, what is more important is that it 525 indicates what decoding mechanism will be required to remove the 526 encoding. 527 </t> 528 <t> 529 compress<iref item="compress (Coding Format)"/> 530 <list> 531 <t> 532 See &compress-coding;. 533 </t> 534 </list> 535 </t> 536 <t> 537 deflate<iref item="deflate (Coding Format)"/> 538 <list> 539 <t> 540 See &deflate-coding;. 541 </t> 542 </list> 543 </t> 544 <t> 545 gzip<iref item="gzip (Coding Format)"/> 546 <list> 547 <t> 548 See &gzip-coding;. 549 </t> 550 </list> 355 551 </t> 356 552 </section> … … 413 609 </t> 414 610 </section> 611 </section> 612 613 <section title="Audience Language" anchor="audience.language"> 614 615 <section title="Language Tags" anchor="language.tags"> 616 <x:anchor-alias value="language-tag"/> 617 <t> 618 A language tag, as defined in <xref target="RFC5646"/>, identifies a 619 natural language spoken, written, or otherwise conveyed by human beings for 620 communication of information to other human beings. Computer languages are 621 explicitly excluded. HTTP uses language tags within the 622 <x:ref>Accept-Language</x:ref> and <x:ref>Content-Language</x:ref> fields. 623 </t> 624 <t> 625 In summary, a language tag is composed of one or more parts: A primary 626 language subtag followed by a possibly empty series of subtags: 627 </t> 628 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="language-tag"/> 629 <x:ref>language-tag</x:ref> = <Language-Tag, defined in <xref target="RFC5646" x:sec="2.1"/>> 630 </artwork></figure> 631 <t> 632 White space is not allowed within the tag and all tags are case-insensitive. 633 The name space of language subtags is administered by the IANA (see 634 <eref target="http://www.iana.org/assignments/language-subtag-registry"/>). 635 </t> 636 <figure> 637 <preamble>Example tags include:</preamble> 638 <artwork type="example"> 639 en, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN 640 </artwork> 641 </figure> 642 <t> 643 See <xref target="RFC5646"/> for further information. 644 </t> 645 </section> 415 646 416 647 <section title="Content-Language" anchor="header.content-language"> … … 463 694 </t> 464 695 </section> 465 466 <section title="Content-Location" anchor="header.content-location"> 467 <iref primary="true" item="Content-Location header field" x:for-anchor=""/> 468 <x:anchor-alias value="Content-Location"/> 469 <t> 470 The "Content-Location" header field supplies a URI that can be used 471 as a specific identifier for the representation in this message. 472 In other words, if one were to perform a GET on this URI at the time 473 of this message's generation, then a <x:ref>200 (OK)</x:ref> response would 474 contain the same representation that is enclosed as payload in this message. 475 </t> 476 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Location"/> 477 <x:ref>Content-Location</x:ref> = <x:ref>absolute-URI</x:ref> / <x:ref>partial-URI</x:ref> 478 </artwork></figure> 479 <t> 480 The Content-Location value is not a replacement for the effective 481 Request URI (&effective-request-uri;). It is representation metadata. 482 It has the same syntax and semantics as the header field of the same name 483 defined for MIME body parts in <xref target="RFC2557" x:fmt="of" x:sec="4"/>. 484 However, its appearance in an HTTP message has some special implications 485 for HTTP recipients. 486 </t> 487 <t> 488 If Content-Location is included in a response message and its value 489 is the same as the effective request URI, then the response payload 490 &SHOULD; be considered a current representation of that resource. 491 For a GET or HEAD request, this is the same as the default semantics 492 when no Content-Location is provided by the server. For a state-changing 493 request like PUT or POST, it implies that the server's response contains 494 the new representation of that resource, thereby distinguishing it from 495 representations that might only report about the action (e.g., "It worked!"). 496 This allows authoring applications to update their local copies without 497 the need for a subsequent GET request. 498 </t> 499 <t> 500 If Content-Location is included in a response message and its value 501 differs from the effective request URI, then the origin server is 502 informing recipients that this representation has its own, presumably 503 more specific, identifier. For a GET or HEAD request, this is an 504 indication that the effective request URI identifies a resource that 505 is subject to content negotiation and the selected representation for 506 this response can also be found at the identified URI. For other 507 methods, such a Content-Location indicates that this representation 508 contains a report on the action's status and the same report is 509 available (for future access with GET) at the given URI. For 510 example, a purchase transaction made via a POST request might 511 include a receipt document as the payload of the <x:ref>200 (OK)</x:ref> 512 response; the Content-Location value provides an identifier for retrieving 513 a copy of that same receipt in the future. 514 </t> 515 <t> 516 If Content-Location is included in a request message, then it &MAY; 517 be interpreted by the origin server as an indication of where the 518 user agent originally obtained the content of the enclosed 519 representation (prior to any subsequent modification of the content 520 by that user agent). In other words, the user agent is providing 521 the same representation metadata that it received with the original 522 representation. However, such interpretation &MUST-NOT; be used to 523 alter the semantics of the method requested by the client. For 524 example, if a client makes a PUT request on a negotiated resource 525 and the origin server accepts that PUT (without redirection), then the 526 new set of values for that resource is expected to be consistent with 527 the one representation supplied in that PUT; the Content-Location 528 cannot be used as a form of reverse content selection that 529 identifies only one of the negotiated representations to be updated. 530 If the user agent had wanted the latter semantics, it would have applied 531 the PUT directly to the Content-Location URI. 532 </t> 533 <t> 534 A Content-Location field received in a request message is transitory 535 information that &SHOULD-NOT; be saved with other representation 536 metadata for use in later responses. The Content-Location's value 537 might be saved for use in other contexts, such as within source links 538 or other metadata. 539 </t> 540 <t> 541 A cache cannot assume that a representation with a Content-Location 542 different from the URI used to retrieve it can be used to respond to 543 later requests on that Content-Location URI. 544 </t> 545 <t> 546 If the Content-Location value is a partial URI, the partial URI is 547 interpreted relative to the effective request URI. 548 </t> 549 </section> 550 </section> 551 552 <section title="Representation Data" anchor="representation.data"> 553 <x:anchor-alias value="representation-data"/> 554 <t> 555 The representation data associated with an HTTP message is 556 either provided as the payload body of the message or 557 referred to by the message semantics and the effective request 558 URI. The representation data is in a format and encoding defined by 559 the representation metadata header fields. 560 </t> 561 <t> 562 The data type of the representation data is determined via the header fields 563 <x:ref>Content-Type</x:ref> and <x:ref>Content-Encoding</x:ref>. 564 These define a two-layer, ordered encoding model: 565 </t> 566 <figure><artwork type="example"> 567 representation-data := Content-Encoding( Content-Type( bits ) ) 568 </artwork></figure> 569 </section> 570 571 <section title="Message Payload" anchor="payload"> 572 <iref item="payload"/> 573 <t> 574 Some HTTP messages transfer a complete or partial representation as the 575 message "<x:dfn>payload</x:dfn>". In some cases, a payload might only 576 contain the associated representation's header fields (e.g., responses to 577 HEAD) or only some part(s) of the representation data 578 (e.g., the <x:ref>206 (Partial Content)</x:ref> status code). 579 </t> 580 <t> 581 The purpose of a payload in a request is defined by the method semantics. 582 In a response, the payload's purpose is defined by both the request method 583 and the response status code. 584 </t> 585 <t> 586 For example, a representation in the payload of a PUT request 587 (<xref target="PUT"/>) represents the desired state of the target resource 588 if the request is successfully applied, whereas a representation in the 589 payload of a POST request (<xref target="POST"/>) represents an anonymous 590 resource for providing data to be processed, such as the information that 591 a user entered within an HTML form. 592 </t> 593 <t> 594 Likewise, the payload of a <x:ref>200 (OK)</x:ref> response to GET 595 (<xref target="GET"/>) contains a representation of the target resource, 596 as observed at the time of the message origination date 597 (<xref target="header.date"/>), whereas the same status code in a response 598 to POST might contain either a representation of the processing result or 599 a current representation of the target resource after applying the 600 processing. Response messages with an error status code usually contain 601 a representation that describes the error and what next steps are suggested 602 for resolving it. 603 </t> 604 605 <section title="Payload Header Fields" anchor="payload.header.fields"> 606 <t> 607 Header fields that specifically describe the payload, rather than the 608 associated representation, are referred to as "payload header fields". 609 Payload header fields are defined in other parts of this specification, 610 due to their impact on message parsing. 611 </t> 612 <texttable align="left"> 613 <ttcol>Header Field Name</ttcol> 614 <ttcol>Defined in...</ttcol> 615 616 <c>Content-Length</c> <c>&header-content-length;</c> 617 <c>Content-Range</c> <c>&header-content-range;</c> 618 <c>Transfer-Encoding</c> <c>&header-transfer-encoding;</c> 619 </texttable> 620 </section> 696 </section> 697 698 <section title="Identification" anchor="identification"> 621 699 622 700 <section title="Identifying the Payload" anchor="identifying.payload"> … … 670 748 </t> 671 749 </section> 750 751 <section title="Content-Location" anchor="header.content-location"> 752 <iref primary="true" item="Content-Location header field" x:for-anchor=""/> 753 <x:anchor-alias value="Content-Location"/> 754 <t> 755 The "Content-Location" header field supplies a URI that can be used 756 as a specific identifier for the representation in this message. 757 In other words, if one were to perform a GET on this URI at the time 758 of this message's generation, then a <x:ref>200 (OK)</x:ref> response would 759 contain the same representation that is enclosed as payload in this message. 760 </t> 761 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Location"/> 762 <x:ref>Content-Location</x:ref> = <x:ref>absolute-URI</x:ref> / <x:ref>partial-URI</x:ref> 763 </artwork></figure> 764 <t> 765 The Content-Location value is not a replacement for the effective 766 Request URI (&effective-request-uri;). It is representation metadata. 767 It has the same syntax and semantics as the header field of the same name 768 defined for MIME body parts in <xref target="RFC2557" x:fmt="of" x:sec="4"/>. 769 However, its appearance in an HTTP message has some special implications 770 for HTTP recipients. 771 </t> 772 <t> 773 If Content-Location is included in a response message and its value 774 is the same as the effective request URI, then the response payload 775 &SHOULD; be considered a current representation of that resource. 776 For a GET or HEAD request, this is the same as the default semantics 777 when no Content-Location is provided by the server. For a state-changing 778 request like PUT or POST, it implies that the server's response contains 779 the new representation of that resource, thereby distinguishing it from 780 representations that might only report about the action (e.g., "It worked!"). 781 This allows authoring applications to update their local copies without 782 the need for a subsequent GET request. 783 </t> 784 <t> 785 If Content-Location is included in a response message and its value 786 differs from the effective request URI, then the origin server is 787 informing recipients that this representation has its own, presumably 788 more specific, identifier. For a GET or HEAD request, this is an 789 indication that the effective request URI identifies a resource that 790 is subject to content negotiation and the selected representation for 791 this response can also be found at the identified URI. For other 792 methods, such a Content-Location indicates that this representation 793 contains a report on the action's status and the same report is 794 available (for future access with GET) at the given URI. For 795 example, a purchase transaction made via a POST request might 796 include a receipt document as the payload of the <x:ref>200 (OK)</x:ref> 797 response; the Content-Location value provides an identifier for retrieving 798 a copy of that same receipt in the future. 799 </t> 800 <t> 801 If Content-Location is included in a request message, then it &MAY; 802 be interpreted by the origin server as an indication of where the 803 user agent originally obtained the content of the enclosed 804 representation (prior to any subsequent modification of the content 805 by that user agent). In other words, the user agent is providing 806 the same representation metadata that it received with the original 807 representation. However, such interpretation &MUST-NOT; be used to 808 alter the semantics of the method requested by the client. For 809 example, if a client makes a PUT request on a negotiated resource 810 and the origin server accepts that PUT (without redirection), then the 811 new set of values for that resource is expected to be consistent with 812 the one representation supplied in that PUT; the Content-Location 813 cannot be used as a form of reverse content selection that 814 identifies only one of the negotiated representations to be updated. 815 If the user agent had wanted the latter semantics, it would have applied 816 the PUT directly to the Content-Location URI. 817 </t> 818 <t> 819 A Content-Location field received in a request message is transitory 820 information that &SHOULD-NOT; be saved with other representation 821 metadata for use in later responses. The Content-Location's value 822 might be saved for use in other contexts, such as within source links 823 or other metadata. 824 </t> 825 <t> 826 A cache cannot assume that a representation with a Content-Location 827 different from the URI used to retrieve it can be used to respond to 828 later requests on that Content-Location URI. 829 </t> 830 <t> 831 If the Content-Location value is a partial URI, the partial URI is 832 interpreted relative to the effective request URI. 833 </t> 834 </section> 835 </section> 836 </section> 837 838 <section title="Representation Data" anchor="representation.data"> 839 <x:anchor-alias value="representation-data"/> 840 <t> 841 The representation data associated with an HTTP message is 842 either provided as the payload body of the message or 843 referred to by the message semantics and the effective request 844 URI. The representation data is in a format and encoding defined by 845 the representation metadata header fields. 846 </t> 847 <t> 848 The data type of the representation data is determined via the header fields 849 <x:ref>Content-Type</x:ref> and <x:ref>Content-Encoding</x:ref>. 850 These define a two-layer, ordered encoding model: 851 </t> 852 <figure><artwork type="example"> 853 representation-data := Content-Encoding( Content-Type( bits ) ) 854 </artwork></figure> 855 </section> 856 857 <section title="Payload Semantics" anchor="payload"> 858 <iref item="payload"/> 859 <t> 860 Some HTTP messages transfer a complete or partial representation as the 861 message "<x:dfn>payload</x:dfn>". In some cases, a payload might only 862 contain the associated representation's header fields (e.g., responses to 863 HEAD) or only some part(s) of the representation data 864 (e.g., the <x:ref>206 (Partial Content)</x:ref> status code). 865 </t> 866 <t> 867 The purpose of a payload in a request is defined by the method semantics. 868 In a response, the payload's purpose is defined by both the request method 869 and the response status code. 870 </t> 871 <t> 872 For example, a representation in the payload of a PUT request 873 (<xref target="PUT"/>) represents the desired state of the target resource 874 if the request is successfully applied, whereas a representation in the 875 payload of a POST request (<xref target="POST"/>) represents an anonymous 876 resource for providing data to be processed, such as the information that 877 a user entered within an HTML form. 878 </t> 879 <t> 880 Likewise, the payload of a <x:ref>200 (OK)</x:ref> response to GET 881 (<xref target="GET"/>) contains a representation of the target resource, 882 as observed at the time of the message origination date 883 (<xref target="header.date"/>), whereas the same status code in a response 884 to POST might contain either a representation of the processing result or 885 a current representation of the target resource after applying the 886 processing. Response messages with an error status code usually contain 887 a representation that describes the error and what next steps are suggested 888 for resolving it. 889 </t> 890 <t> 891 Header fields that specifically describe the payload, rather than the 892 associated representation, are referred to as "payload header fields". 893 Payload header fields are defined in other parts of this specification, 894 due to their impact on message parsing. 895 </t> 896 <texttable align="left"> 897 <ttcol>Header Field Name</ttcol> 898 <ttcol>Defined in...</ttcol> 899 900 <c>Content-Length</c> <c>&header-content-length;</c> 901 <c>Content-Range</c> <c>&header-content-range;</c> 902 <c>Transfer-Encoding</c> <c>&header-transfer-encoding;</c> 903 </texttable> 672 904 </section> 673 905 … … 833 1065 </section> 834 1066 </section> 1067 </section> 1068 1069 <section title="Product Tokens" anchor="product.tokens"> 1070 <x:anchor-alias value="product"/> 1071 <x:anchor-alias value="product-version"/> 1072 <t> 1073 Product tokens are used to allow communicating applications to 1074 identify themselves by software name and version. Most fields using 1075 product tokens also allow sub-products which form a significant part 1076 of the application to be listed, separated by whitespace. By 1077 convention, the products are listed in order of their significance 1078 for identifying the application. 1079 </t> 1080 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="product"/><iref primary="true" item="Grammar" subitem="product-version"/> 1081 <x:ref>product</x:ref> = <x:ref>token</x:ref> ["/" <x:ref>product-version</x:ref>] 1082 <x:ref>product-version</x:ref> = <x:ref>token</x:ref> 1083 </artwork></figure> 1084 <t> 1085 Examples: 1086 </t> 1087 <figure><artwork type="example"> 1088 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 1089 Server: Apache/0.8.4 1090 </artwork></figure> 1091 <t> 1092 Product tokens &SHOULD; be short and to the point. They &MUST-NOT; be 1093 used for advertising or other non-essential information. Although any 1094 token octet &MAY; appear in a product-version, this token &SHOULD; 1095 only be used for a version identifier (i.e., successive versions of 1096 the same product &SHOULD; only differ in the product-version portion of 1097 the product value). 1098 </t> 835 1099 </section> 836 1100 … … 2091 2355 </section> 2092 2356 2093 <section title="Authentication " anchor="request.auth">2357 <section title="Authentication Credentials" anchor="request.auth"> 2094 2358 <texttable align="left"> 2095 2359 <ttcol>Header Field Name</ttcol> … … 3233 3497 </texttable> 3234 3498 3235 <section title="Date" anchor="header.date"> 3236 <iref primary="true" item="Date header field" x:for-anchor=""/> 3237 <x:anchor-alias value="Date"/> 3238 <t> 3239 The "Date" header field represents the date and time at which 3240 the message was originated, having the same semantics as the Origination 3241 Date Field (orig-date) defined in <xref target="RFC5322" x:fmt="of" x:sec="3.6.1"/>. 3242 The field value is an HTTP-date, as defined in <xref target="http.date"/>; 3243 it &MUST; be sent in rfc1123-date format. 3244 </t> 3245 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Date"/> 3246 <x:ref>Date</x:ref> = <x:ref>HTTP-date</x:ref> 3247 </artwork></figure> 3248 <t> 3249 An example is 3250 </t> 3251 <figure><artwork type="example"> 3252 Date: Tue, 15 Nov 1994 08:12:31 GMT 3253 </artwork></figure> 3254 <t> 3255 Origin servers &MUST; include a Date header field in all responses, 3256 except in these cases: 3257 <list style="numbers"> 3258 <t>If the response status code is <x:ref>100 (Continue)</x:ref> or 3259 <x:ref>101 (Switching Protocols)</x:ref>, the response &MAY; include a 3260 Date header field, at the server's option.</t> 3261 3262 <t>If the response status code conveys a server error, e.g., <x:ref>500 3263 (Internal Server Error)</x:ref> or <x:ref>503 (Service Unavailable)</x:ref>, 3264 and it is inconvenient or impossible to generate a valid Date.</t> 3265 3266 <t>If the server does not have a clock that can provide a 3267 reasonable approximation of the current time, its responses 3268 &MUST-NOT; include a Date header field.</t> 3269 </list> 3270 </t> 3271 <t> 3272 A received message that does not have a Date header field &MUST; be 3273 assigned one by the recipient if the message will be cached by that 3274 recipient. 3275 </t> 3276 <t> 3277 Clients can use the Date header field as well; in order to keep request 3278 messages small, they are advised not to include it when it doesn't convey 3279 any useful information (as is usually the case for requests that do not 3280 contain a payload). 3281 </t> 3282 <t> 3283 The HTTP-date sent in a Date header field &SHOULD-NOT; represent a date and 3284 time subsequent to the generation of the message. It &SHOULD; represent 3285 the best available approximation of the date and time of message 3286 generation, unless the implementation has no means of generating a 3287 reasonably accurate date and time. In theory, the date ought to 3288 represent the moment just before the payload is generated. In 3289 practice, the date can be generated at any time during the message 3290 origination without affecting its semantic value. 3291 </t> 3292 </section> 3293 3294 <section title="Location" anchor="header.location"> 3295 <iref primary="true" item="Location header field" x:for-anchor=""/> 3296 <x:anchor-alias value="Location"/> 3297 <t> 3298 The "Location" header field &MAY; be sent in responses to refer to 3299 a specific resource in accordance with the semantics of the status 3300 code. 3301 </t> 3302 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Location"/> 3303 <x:ref>Location</x:ref> = <x:ref>URI-reference</x:ref> 3304 </artwork></figure> 3305 <t> 3306 For <x:ref>201 (Created)</x:ref> responses, the Location is the URI of the 3307 new resource which was created by the request. For <x:ref>3xx (Redirection)</x:ref> 3308 responses, the location &SHOULD; indicate the server's preferred URI for 3309 automatic redirection to the resource. 3310 </t> 3311 <t> 3312 The field value consists of a single URI-reference. When it has the form 3313 of a relative reference (<xref target="RFC3986" x:fmt="," x:sec="4.2"/>), 3314 the final value is computed by resolving it against the effective request 3315 URI (<xref target="RFC3986" x:fmt="," x:sec="5"/>). If the original URI, as 3316 navigated to by the user agent, did contain a fragment identifier, and the 3317 final value does not, then the original URI's fragment identifier is added 3318 to the final value. 3319 </t> 3320 <figure> 3321 <preamble>For example, the original URI "http://www.example.org/~tim", combined with a field value given as:</preamble><!--DO NOT DARE changing the vertical spacing below, it's necessary this way for xml2rfc--> 3322 <artwork type="example"> 3323 Location: /pub/WWW/People.html#tim 3324 </artwork> 3325 <postamble>would result in a final value of "http://www.example.org/pub/WWW/People.html#tim"</postamble> 3326 </figure> 3327 <figure> 3328 <preamble>An original URI "http://www.example.org/index.html#larry", combined with a field value given as:</preamble><!--DO NOT DARE changing the vertical spacing below, it's necessary this way for xml2rfc--> 3329 <artwork type="example"> 3330 Location: http://www.example.net/index.html 3331 </artwork> 3332 <postamble>would result in a final value of "http://www.example.net/index.html#larry", preserving the original fragment identifier.</postamble> 3333 </figure> 3334 <x:note> 3335 <t> 3336 &Note; Some recipients attempt to recover from Location fields 3337 that are not valid URI references. This specification does not mandate or 3338 define such processing, but does allow it. 3339 </t> 3340 </x:note> 3341 <t> 3342 There are circumstances in which a fragment identifier in a Location URI 3343 would not be appropriate. For instance, when it appears in a <x:ref>201 3344 (Created)</x:ref> response, where the Location header field specifies the 3345 URI for the entire created resource. 3346 </t> 3347 <x:note> 3348 <t> 3349 &Note; The <x:ref>Content-Location</x:ref> header field 3350 (&header-content-location;) differs from Location in that the 3351 Content-Location identifies the most specific resource corresponding to the 3352 enclosed representation. It is therefore possible for a response to contain 3353 header fields for both Location and Content-Location. 3354 </t> 3355 </x:note> 3356 </section> 3357 3358 <section title="Retry-After" anchor="header.retry-after"> 3359 <iref primary="true" item="Retry-After header field" x:for-anchor=""/> 3360 <x:anchor-alias value="Retry-After"/> 3361 <t> 3362 The header "Retry-After" field can be used with a <x:ref>503 (Service 3363 Unavailable)</x:ref> response to indicate how long the service is expected to 3364 be unavailable to the requesting client. This field &MAY; also be used 3365 with any <x:ref>3xx (Redirection)</x:ref> response to indicate the minimum time the 3366 user-agent is asked to wait before issuing the redirected request. 3367 </t> 3368 <t> 3369 The value of this field can be either an HTTP-date or an integer number 3370 of seconds (in decimal) after the time of the response. 3371 </t> 3372 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Retry-After"/> 3373 <x:ref>Retry-After</x:ref> = <x:ref>HTTP-date</x:ref> / <x:ref>delta-seconds</x:ref> 3374 </artwork></figure> 3375 <t anchor="rule.delta-seconds"> 3376 <x:anchor-alias value="delta-seconds"/> 3377 Time spans are non-negative decimal integers, representing time in 3378 seconds. 3379 </t> 3380 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="delta-seconds"/> 3381 <x:ref>delta-seconds</x:ref> = 1*<x:ref>DIGIT</x:ref> 3382 </artwork></figure> 3383 <t> 3384 Two examples of its use are 3385 </t> 3386 <figure><artwork type="example"> 3387 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 3388 Retry-After: 120 3389 </artwork></figure> 3390 <t> 3391 In the latter example, the delay is 2 minutes. 3392 </t> 3393 </section> 3394 </section> 3395 3396 <section title="Selected Representation Header Fields" anchor="selected.representation"> 3397 <t><iref primary="true" item="selected representation"/> 3398 We use the term "<x:dfn>selected representation</x:dfn>" to refer to the 3399 the current representation of a target resource that would have been 3400 selected in a successful response if the same request had used the 3401 method GET and excluded any conditional request header fields. 3402 </t> 3403 <t> 3404 Additional header fields define metadata about the selected 3405 representation, which might differ from the representation included 3406 in the message for responses to some state-changing methods. 3407 The following header fields are defined as selected representation 3408 metadata: 3409 </t> 3410 <texttable align="left"> 3411 <ttcol>Header Field Name</ttcol> 3412 <ttcol>Defined in...</ttcol> 3413 3414 <c>ETag</c> <c>&header-etag;</c> 3415 <c>Last-Modified</c> <c>&header-last-modified;</c> 3416 <c>Vary</c> <c><xref target="header.vary"/></c> 3417 </texttable> 3418 3419 <section anchor="header.vary" title="Vary"> 3420 <iref item="Vary header field" primary="true" x:for-anchor="" /> 3421 <x:anchor-alias value="Vary"/> 3422 <t> 3423 The "Vary" header field conveys the set of header fields 3424 that were used to select the representation. 3425 </t> 3426 <t> 3427 Caches use this information as part of determining whether a stored 3428 response can be used to satisfy a given request (&caching-neg-resp;). 3429 </t> 3430 <t> 3431 In uncacheable or stale responses, the Vary field value advises the user 3432 agent about the criteria that were used to select the representation. 3433 </t> 3434 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Vary"/> 3435 <x:ref>Vary</x:ref> = "*" / 1#<x:ref>field-name</x:ref> 3436 </artwork></figure> 3437 <t> 3438 The set of header fields named by the Vary field value is known as the 3439 selecting header fields. 3440 </t> 3441 <t> 3442 A server &SHOULD; include a Vary header field with any cacheable response 3443 that is subject to proactive negotiation. Doing so allows a cache to 3444 properly interpret future requests on that resource and informs the user 3445 agent about the presence of negotiation on that resource. A server &MAY; 3446 include a Vary header field with a non-cacheable response that is subject 3447 to proactive negotiation, since this might provide the user agent with 3448 useful information about the dimensions over which the response varies at 3449 the time of the response. 3450 </t> 3451 <t> 3452 A Vary field value of "*" signals that unspecified parameters not limited 3453 to the header fields (e.g., the network address of the client), play a 3454 role in the selection of the response representation; therefore, a cache 3455 cannot determine whether this response is appropriate. A proxy &MUST-NOT; 3456 generate the "*" value. 3457 </t> 3458 <t> 3459 The field-names given are not limited to the set of standard header 3460 fields defined by this specification. Field names are case-insensitive. 3461 </t> 3462 </section> 3463 </section> 3464 3465 <section title="Authentication Challenges" anchor="response.auth"> 3466 <t> 3467 Authentication challenges indicate what mechanisms are available for the 3468 client to provide authentication credentials in future requests. 3469 </t> 3470 <texttable align="left"> 3471 <ttcol>Header Field Name</ttcol><ttcol>Defined in...</ttcol> 3472 3473 <c>WWW-Authenticate</c> <c>&header-www-authenticate;</c> 3474 <c>Proxy-Authenticate</c> <c>&header-proxy-authenticate;</c> 3475 </texttable> 3476 </section> 3477 3478 <section title="Informative" anchor="response.inform"> 3479 <t> 3480 The remaining response header fields provide more information about 3481 the target resource for potential use in later requests. 3482 </t> 3483 <texttable align="left"> 3484 <ttcol>Header Field Name</ttcol><ttcol>Defined in...</ttcol> 3485 3486 <c>Accept-Ranges</c> <c>&header-accept-ranges;</c> 3487 <c>Allow</c> <c><xref target="header.allow"/></c> 3488 <c>Server</c> <c><xref target="header.server"/></c> 3489 </texttable> 3490 3491 <section title="Allow" anchor="header.allow"> 3492 <iref primary="true" item="Allow header field" x:for-anchor=""/> 3493 <x:anchor-alias value="Allow"/> 3494 <t> 3495 The "Allow" header field lists the set of methods advertised as 3496 supported by the target resource. The purpose of this field is strictly to 3497 inform the recipient of valid request methods associated with the resource. 3498 </t> 3499 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Allow"/> 3500 <x:ref>Allow</x:ref> = #<x:ref>method</x:ref> 3501 </artwork></figure> 3502 <t> 3503 Example of use: 3504 </t> 3505 <figure><artwork type="example"> 3506 Allow: GET, HEAD, PUT 3507 </artwork></figure> 3508 <t> 3509 The actual set of allowed methods is defined by the origin server at the 3510 time of each request. 3511 </t> 3512 <t> 3513 A proxy &MUST-NOT; modify the Allow header field — it does not need to 3514 understand all the methods specified in order to handle them according to 3515 the generic message handling rules. 3516 </t> 3517 </section> 3518 3519 <section title="Server" anchor="header.server"> 3520 <iref primary="true" item="Server header field" x:for-anchor=""/> 3521 <x:anchor-alias value="Server"/> 3522 <t> 3523 The "Server" header field contains information about the 3524 software used by the origin server to handle the request. 3525 </t> 3526 <t> 3527 The field can contain multiple 3528 product tokens (<xref target="product.tokens"/>) and 3529 comments (&header-fields;) identifying the server and any significant 3530 subproducts. The product tokens are listed in order of their significance 3531 for identifying the application. 3532 </t> 3533 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Server"/> 3534 <x:ref>Server</x:ref> = <x:ref>product</x:ref> *( <x:ref>RWS</x:ref> ( <x:ref>product</x:ref> / <x:ref>comment</x:ref> ) ) 3535 </artwork></figure> 3536 <t> 3537 Example: 3538 </t> 3539 <figure><artwork type="example"> 3540 Server: CERN/3.0 libwww/2.17 3541 </artwork></figure> 3542 <t> 3543 If the response is being forwarded through a proxy, the proxy application 3544 &MUST-NOT; modify the <x:ref>Server</x:ref> header field. Instead, it 3545 &MUST; include a <x:ref>Via</x:ref> field (as described in &header-via;). 3546 </t> 3547 <x:note> 3548 <t> 3549 &Note; Revealing the specific software version of the server might 3550 allow the server machine to become more vulnerable to attacks 3551 against software that is known to contain security holes. Server 3552 implementers are encouraged to make this field a configurable 3553 option. 3554 </t> 3555 </x:note> 3556 </section> 3557 </section> 3558 </section> 3559 3560 <section title="Protocol Parameters" anchor="protocol.parameters"> 3499 <section title="Origination Date" anchor="origination.date"> 3500 3561 3501 <section title="Date/Time Formats" anchor="http.date"> 3562 3502 <x:anchor-alias value="HTTP-date"/> … … 3704 3644 </section> 3705 3645 3706 <section title="Product Tokens" anchor="product.tokens"> 3707 <x:anchor-alias value="product"/> 3708 <x:anchor-alias value="product-version"/> 3709 <t> 3710 Product tokens are used to allow communicating applications to 3711 identify themselves by software name and version. Most fields using 3712 product tokens also allow sub-products which form a significant part 3713 of the application to be listed, separated by whitespace. By 3714 convention, the products are listed in order of their significance 3715 for identifying the application. 3716 </t> 3717 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="product"/><iref primary="true" item="Grammar" subitem="product-version"/> 3718 <x:ref>product</x:ref> = <x:ref>token</x:ref> ["/" <x:ref>product-version</x:ref>] 3719 <x:ref>product-version</x:ref> = <x:ref>token</x:ref> 3646 <section title="Date" anchor="header.date"> 3647 <iref primary="true" item="Date header field" x:for-anchor=""/> 3648 <x:anchor-alias value="Date"/> 3649 <t> 3650 The "Date" header field represents the date and time at which 3651 the message was originated, having the same semantics as the Origination 3652 Date Field (orig-date) defined in <xref target="RFC5322" x:fmt="of" x:sec="3.6.1"/>. 3653 The field value is an HTTP-date, as defined in <xref target="http.date"/>; 3654 it &MUST; be sent in rfc1123-date format. 3655 </t> 3656 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Date"/> 3657 <x:ref>Date</x:ref> = <x:ref>HTTP-date</x:ref> 3720 3658 </artwork></figure> 3721 3659 <t> 3722 Examples:3660 An example is 3723 3661 </t> 3724 3662 <figure><artwork type="example"> 3725 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 3726 Server: Apache/0.8.4 3663 Date: Tue, 15 Nov 1994 08:12:31 GMT 3727 3664 </artwork></figure> 3728 3665 <t> 3729 Product tokens &SHOULD; be short and to the point. They &MUST-NOT; be 3730 used for advertising or other non-essential information. Although any 3731 token octet &MAY; appear in a product-version, this token &SHOULD; 3732 only be used for a version identifier (i.e., successive versions of 3733 the same product &SHOULD; only differ in the product-version portion of 3734 the product value). 3735 </t> 3736 </section> 3737 3738 <section title="Character Encodings (charset)" anchor="character.sets"> 3739 <t> 3740 HTTP uses charset names to indicate the character encoding of a 3741 textual representation. 3742 </t> 3743 <t anchor="rule.charset"> 3744 <x:anchor-alias value="charset"/> 3745 A character encoding is identified by a case-insensitive token. The 3746 complete set of tokens is defined by the IANA Character Set registry 3747 (<eref target="http://www.iana.org/assignments/character-sets"/>). 3748 </t> 3749 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="charset"/> 3750 <x:ref>charset</x:ref> = <x:ref>token</x:ref> 3666 Origin servers &MUST; include a Date header field in all responses, 3667 except in these cases: 3668 <list style="numbers"> 3669 <t>If the response status code is <x:ref>100 (Continue)</x:ref> or 3670 <x:ref>101 (Switching Protocols)</x:ref>, the response &MAY; include a 3671 Date header field, at the server's option.</t> 3672 3673 <t>If the response status code conveys a server error, e.g., <x:ref>500 3674 (Internal Server Error)</x:ref> or <x:ref>503 (Service Unavailable)</x:ref>, 3675 and it is inconvenient or impossible to generate a valid Date.</t> 3676 3677 <t>If the server does not have a clock that can provide a 3678 reasonable approximation of the current time, its responses 3679 &MUST-NOT; include a Date header field.</t> 3680 </list> 3681 </t> 3682 <t> 3683 A received message that does not have a Date header field &MUST; be 3684 assigned one by the recipient if the message will be cached by that 3685 recipient. 3686 </t> 3687 <t> 3688 Clients can use the Date header field as well; in order to keep request 3689 messages small, they are advised not to include it when it doesn't convey 3690 any useful information (as is usually the case for requests that do not 3691 contain a payload). 3692 </t> 3693 <t> 3694 The HTTP-date sent in a Date header field &SHOULD-NOT; represent a date and 3695 time subsequent to the generation of the message. It &SHOULD; represent 3696 the best available approximation of the date and time of message 3697 generation, unless the implementation has no means of generating a 3698 reasonably accurate date and time. In theory, the date ought to 3699 represent the moment just before the payload is generated. In 3700 practice, the date can be generated at any time during the message 3701 origination without affecting its semantic value. 3702 </t> 3703 </section> 3704 </section> 3705 3706 <section title="Location" anchor="header.location"> 3707 <iref primary="true" item="Location header field" x:for-anchor=""/> 3708 <x:anchor-alias value="Location"/> 3709 <t> 3710 The "Location" header field &MAY; be sent in responses to refer to 3711 a specific resource in accordance with the semantics of the status 3712 code. 3713 </t> 3714 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Location"/> 3715 <x:ref>Location</x:ref> = <x:ref>URI-reference</x:ref> 3751 3716 </artwork></figure> 3752 3717 <t> 3753 Although HTTP allows an arbitrary token to be used as a charset 3754 value, any token that has a predefined value within the IANA 3755 Character Set registry &MUST; represent the character encoding defined 3756 by that registry. Applications &SHOULD; limit their use of character 3757 encodings to those defined within the IANA registry. 3758 </t> 3759 <t> 3760 HTTP uses charset in two contexts: within an <x:ref>Accept-Charset</x:ref> 3761 request header field (in which the charset value is an unquoted token) and 3762 as the value of a parameter in a <x:ref>Content-Type</x:ref> header field 3763 (within a request or response), in which case the parameter value of the 3764 charset parameter can be quoted. 3765 </t> 3766 <t> 3767 Implementers need to be aware of IETF character set requirements <xref target="RFC3629"/> 3768 <xref target="RFC2277"/>. 3769 </t> 3770 </section> 3771 3772 <section title="Content Codings" anchor="content.codings"> 3773 <x:anchor-alias value="content-coding"/> 3774 <t> 3775 Content coding values indicate an encoding transformation that has 3776 been or can be applied to a representation. Content codings are primarily 3777 used to allow a representation to be compressed or otherwise usefully 3778 transformed without losing the identity of its underlying media type 3779 and without loss of information. Frequently, the representation is stored in 3780 coded form, transmitted directly, and only decoded by the recipient. 3781 </t> 3782 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="content-coding"/> 3783 <x:ref>content-coding</x:ref> = <x:ref>token</x:ref> 3784 </artwork></figure> 3785 <t> 3786 All content-coding values are case-insensitive. HTTP/1.1 uses 3787 content-coding values in the <x:ref>Accept-Encoding</x:ref> 3788 (<xref target="header.accept-encoding"/>) and <x:ref>Content-Encoding</x:ref> 3789 (<xref target="header.content-encoding"/>) header fields. Although the value 3790 describes the content-coding, what is more important is that it 3791 indicates what decoding mechanism will be required to remove the 3792 encoding. 3793 </t> 3794 <t> 3795 compress<iref item="compress (Coding Format)"/> 3796 <list> 3797 <t> 3798 See &compress-coding;. 3799 </t> 3800 </list> 3801 </t> 3802 <t> 3803 deflate<iref item="deflate (Coding Format)"/> 3804 <list> 3805 <t> 3806 See &deflate-coding;. 3807 </t> 3808 </list> 3809 </t> 3810 <t> 3811 gzip<iref item="gzip (Coding Format)"/> 3812 <list> 3813 <t> 3814 See &gzip-coding;. 3815 </t> 3816 </list> 3817 </t> 3818 </section> 3819 3820 <section title="Media Types" anchor="media.types"> 3821 <x:anchor-alias value="media-type"/> 3822 <x:anchor-alias value="type"/> 3823 <x:anchor-alias value="subtype"/> 3824 <t> 3825 HTTP uses Internet Media Types <xref target="RFC2046"/> in the 3826 <x:ref>Content-Type</x:ref> (<xref target="header.content-type"/>) 3827 and <x:ref>Accept</x:ref> (<xref target="header.accept"/>) header fields in 3828 order to provide open and extensible data typing and type negotiation. 3829 </t> 3830 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="media-type"/><iref primary="true" item="Grammar" subitem="type"/><iref primary="true" item="Grammar" subitem="subtype"/> 3831 <x:ref>media-type</x:ref> = <x:ref>type</x:ref> "/" <x:ref>subtype</x:ref> *( <x:ref>OWS</x:ref> ";" <x:ref>OWS</x:ref> <x:ref>parameter</x:ref> ) 3832 <x:ref>type</x:ref> = <x:ref>token</x:ref> 3833 <x:ref>subtype</x:ref> = <x:ref>token</x:ref> 3834 </artwork></figure> 3835 <t anchor="rule.parameter"> 3836 <x:anchor-alias value="attribute"/> 3837 <x:anchor-alias value="parameter"/> 3838 <x:anchor-alias value="value"/> 3839 The type/subtype &MAY; be followed by parameters in the form of 3840 attribute/value pairs. 3841 </t> 3842 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="parameter"/><iref primary="true" item="Grammar" subitem="attribute"/><iref primary="true" item="Grammar" subitem="value"/> 3843 <x:ref>parameter</x:ref> = <x:ref>attribute</x:ref> "=" <x:ref>value</x:ref> 3844 <x:ref>attribute</x:ref> = <x:ref>token</x:ref> 3845 <x:ref>value</x:ref> = <x:ref>word</x:ref> 3846 </artwork></figure> 3847 <t> 3848 The type, subtype, and parameter attribute names are case-insensitive. 3849 Parameter values might or might not be case-sensitive, depending on the 3850 semantics of the parameter name. The presence or absence of a parameter might 3851 be significant to the processing of a media-type, depending on its 3852 definition within the media type registry. 3853 </t> 3854 <t> 3855 A parameter value that matches the <x:ref>token</x:ref> production can be 3856 transmitted as either a token or within a quoted-string. The quoted and 3857 unquoted values are equivalent. 3858 </t> 3859 <t> 3860 Media-type values are registered with the Internet Assigned Number 3861 Authority (IANA). The media type registration process is 3862 outlined in <xref target="RFC4288"/>. Use of non-registered media types is 3863 discouraged. 3864 </t> 3865 3866 <section title="Canonicalization and Text Defaults" anchor="canonicalization.and.text.defaults"> 3867 <t> 3868 Internet media types are registered with a canonical form. A 3869 representation transferred via HTTP messages &MUST; be in the 3870 appropriate canonical form prior to its transmission except for 3871 "text" types, as defined in the next paragraph. 3872 </t> 3873 <t> 3874 When in canonical form, media subtypes of the "text" type use CRLF as 3875 the text line break. HTTP relaxes this requirement and allows the 3876 transport of text media with plain CR or LF alone representing a line 3877 break when it is done consistently for an entire representation. HTTP 3878 applications &MUST; accept CRLF, bare CR, and bare LF as indicating 3879 a line break in text media received via HTTP. In 3880 addition, if the text is in a character encoding that does not 3881 use octets 13 and 10 for CR and LF respectively, as is the case for 3882 some multi-byte character encodings, HTTP allows the use of whatever octet 3883 sequences are defined by that character encoding to represent the 3884 equivalent of CR and LF for line breaks. This flexibility regarding 3885 line breaks applies only to text media in the payload body; a bare CR 3886 or LF &MUST-NOT; be substituted for CRLF within any of the HTTP control 3887 structures (such as header fields and multipart boundaries). 3888 </t> 3889 <t> 3890 If a representation is encoded with a content-coding, the underlying 3891 data &MUST; be in a form defined above prior to being encoded. 3892 </t> 3893 </section> 3894 3895 <section title="Multipart Types" anchor="multipart.types"> 3896 <t> 3897 MIME provides for a number of "multipart" types — encapsulations of 3898 one or more representations within a single message body. All multipart 3899 types share a common syntax, as defined in <xref target="RFC2046" x:sec="5.1.1" x:fmt="of"/>, 3900 and include a boundary parameter as part of the media type 3901 value. The message body is itself a protocol element; a sender &MUST; 3902 generate only CRLF to represent line breaks between body-parts. 3903 </t> 3904 <t> 3905 In general, HTTP treats a multipart message body no differently than 3906 any other media type: strictly as payload. HTTP does not use the 3907 multipart boundary as an indicator of message body length. 3908 <!-- jre: re-insert removed text pointing to caching? --> 3909 In all other respects, an HTTP user agent &SHOULD; follow the same or similar 3910 behavior as a MIME user agent would upon receipt of a multipart type. 3911 The MIME header fields within each body-part of a multipart message body 3912 do not have any significance to HTTP beyond that defined by 3913 their MIME semantics. 3914 </t> 3915 <t> 3916 A recipient &MUST; treat an unrecognized multipart subtype 3917 as being equivalent to "multipart/mixed". 3918 </t> 3718 For <x:ref>201 (Created)</x:ref> responses, the Location is the URI of the 3719 new resource which was created by the request. For <x:ref>3xx (Redirection)</x:ref> 3720 responses, the location &SHOULD; indicate the server's preferred URI for 3721 automatic redirection to the resource. 3722 </t> 3723 <t> 3724 The field value consists of a single URI-reference. When it has the form 3725 of a relative reference (<xref target="RFC3986" x:fmt="," x:sec="4.2"/>), 3726 the final value is computed by resolving it against the effective request 3727 URI (<xref target="RFC3986" x:fmt="," x:sec="5"/>). If the original URI, as 3728 navigated to by the user agent, did contain a fragment identifier, and the 3729 final value does not, then the original URI's fragment identifier is added 3730 to the final value. 3731 </t> 3732 <figure> 3733 <preamble>For example, the original URI "http://www.example.org/~tim", combined with a field value given as:</preamble><!--DO NOT DARE changing the vertical spacing below, it's necessary this way for xml2rfc--> 3734 <artwork type="example"> 3735 Location: /pub/WWW/People.html#tim 3736 </artwork> 3737 <postamble>would result in a final value of "http://www.example.org/pub/WWW/People.html#tim"</postamble> 3738 </figure> 3739 <figure> 3740 <preamble>An original URI "http://www.example.org/index.html#larry", combined with a field value given as:</preamble><!--DO NOT DARE changing the vertical spacing below, it's necessary this way for xml2rfc--> 3741 <artwork type="example"> 3742 Location: http://www.example.net/index.html 3743 </artwork> 3744 <postamble>would result in a final value of "http://www.example.net/index.html#larry", preserving the original fragment identifier.</postamble> 3745 </figure> 3919 3746 <x:note> 3920 3747 <t> 3921 &Note; The "multipart/form-data" type has been specifically defined3922 for carrying form data suitable for processing via the POST3923 request method, as described in <xref target="RFC2388"/>.3748 &Note; Some recipients attempt to recover from Location fields 3749 that are not valid URI references. This specification does not mandate or 3750 define such processing, but does allow it. 3924 3751 </t> 3925 3752 </x:note> 3926 </section> 3927 </section> 3928 3929 <section title="Language Tags" anchor="language.tags"> 3930 <x:anchor-alias value="language-tag"/> 3931 <t> 3932 A language tag, as defined in <xref target="RFC5646"/>, identifies a 3933 natural language spoken, written, or otherwise conveyed by human beings for 3934 communication of information to other human beings. Computer languages are 3935 explicitly excluded. HTTP uses language tags within the 3936 <x:ref>Accept-Language</x:ref> and <x:ref>Content-Language</x:ref> fields. 3937 </t> 3938 <t> 3939 In summary, a language tag is composed of one or more parts: A primary 3940 language subtag followed by a possibly empty series of subtags: 3941 </t> 3942 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="language-tag"/> 3943 <x:ref>language-tag</x:ref> = <Language-Tag, defined in <xref target="RFC5646" x:sec="2.1"/>> 3753 <t> 3754 There are circumstances in which a fragment identifier in a Location URI 3755 would not be appropriate. For instance, when it appears in a <x:ref>201 3756 (Created)</x:ref> response, where the Location header field specifies the 3757 URI for the entire created resource. 3758 </t> 3759 <x:note> 3760 <t> 3761 &Note; The <x:ref>Content-Location</x:ref> header field 3762 (&header-content-location;) differs from Location in that the 3763 Content-Location identifies the most specific resource corresponding to the 3764 enclosed representation. It is therefore possible for a response to contain 3765 header fields for both Location and Content-Location. 3766 </t> 3767 </x:note> 3768 </section> 3769 3770 <section title="Retry-After" anchor="header.retry-after"> 3771 <iref primary="true" item="Retry-After header field" x:for-anchor=""/> 3772 <x:anchor-alias value="Retry-After"/> 3773 <t> 3774 The header "Retry-After" field can be used with a <x:ref>503 (Service 3775 Unavailable)</x:ref> response to indicate how long the service is expected to 3776 be unavailable to the requesting client. This field &MAY; also be used 3777 with any <x:ref>3xx (Redirection)</x:ref> response to indicate the minimum time the 3778 user-agent is asked to wait before issuing the redirected request. 3779 </t> 3780 <t> 3781 The value of this field can be either an HTTP-date or an integer number 3782 of seconds (in decimal) after the time of the response. 3783 </t> 3784 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Retry-After"/> 3785 <x:ref>Retry-After</x:ref> = <x:ref>HTTP-date</x:ref> / <x:ref>delta-seconds</x:ref> 3944 3786 </artwork></figure> 3945 <t> 3946 White space is not allowed within the tag and all tags are case-insensitive. 3947 The name space of language subtags is administered by the IANA (see 3948 <eref target="http://www.iana.org/assignments/language-subtag-registry"/>). 3949 </t> 3950 <figure> 3951 <preamble>Example tags include:</preamble> 3952 <artwork type="example"> 3953 en, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN 3954 </artwork> 3955 </figure> 3956 <t> 3957 See <xref target="RFC5646"/> for further information. 3958 </t> 3787 <t anchor="rule.delta-seconds"> 3788 <x:anchor-alias value="delta-seconds"/> 3789 Time spans are non-negative decimal integers, representing time in 3790 seconds. 3791 </t> 3792 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="delta-seconds"/> 3793 <x:ref>delta-seconds</x:ref> = 1*<x:ref>DIGIT</x:ref> 3794 </artwork></figure> 3795 <t> 3796 Two examples of its use are 3797 </t> 3798 <figure><artwork type="example"> 3799 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 3800 Retry-After: 120 3801 </artwork></figure> 3802 <t> 3803 In the latter example, the delay is 2 minutes. 3804 </t> 3805 </section> 3806 </section> 3807 3808 <section title="Selected Representation Header Fields" anchor="selected.representation"> 3809 <t><iref primary="true" item="selected representation"/> 3810 We use the term "<x:dfn>selected representation</x:dfn>" to refer to the 3811 the current representation of a target resource that would have been 3812 selected in a successful response if the same request had used the 3813 method GET and excluded any conditional request header fields. 3814 </t> 3815 <t> 3816 Additional header fields define metadata about the selected 3817 representation, which might differ from the representation included 3818 in the message for responses to some state-changing methods. 3819 The following header fields are defined as selected representation 3820 metadata: 3821 </t> 3822 <texttable align="left"> 3823 <ttcol>Header Field Name</ttcol> 3824 <ttcol>Defined in...</ttcol> 3825 3826 <c>ETag</c> <c>&header-etag;</c> 3827 <c>Last-Modified</c> <c>&header-last-modified;</c> 3828 <c>Vary</c> <c><xref target="header.vary"/></c> 3829 </texttable> 3830 3831 <section anchor="header.vary" title="Vary"> 3832 <iref item="Vary header field" primary="true" x:for-anchor="" /> 3833 <x:anchor-alias value="Vary"/> 3834 <t> 3835 The "Vary" header field conveys the set of header fields 3836 that were used to select the representation. 3837 </t> 3838 <t> 3839 Caches use this information as part of determining whether a stored 3840 response can be used to satisfy a given request (&caching-neg-resp;). 3841 </t> 3842 <t> 3843 In uncacheable or stale responses, the Vary field value advises the user 3844 agent about the criteria that were used to select the representation. 3845 </t> 3846 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Vary"/> 3847 <x:ref>Vary</x:ref> = "*" / 1#<x:ref>field-name</x:ref> 3848 </artwork></figure> 3849 <t> 3850 The set of header fields named by the Vary field value is known as the 3851 selecting header fields. 3852 </t> 3853 <t> 3854 A server &SHOULD; include a Vary header field with any cacheable response 3855 that is subject to proactive negotiation. Doing so allows a cache to 3856 properly interpret future requests on that resource and informs the user 3857 agent about the presence of negotiation on that resource. A server &MAY; 3858 include a Vary header field with a non-cacheable response that is subject 3859 to proactive negotiation, since this might provide the user agent with 3860 useful information about the dimensions over which the response varies at 3861 the time of the response. 3862 </t> 3863 <t> 3864 A Vary field value of "*" signals that unspecified parameters not limited 3865 to the header fields (e.g., the network address of the client), play a 3866 role in the selection of the response representation; therefore, a cache 3867 cannot determine whether this response is appropriate. A proxy &MUST-NOT; 3868 generate the "*" value. 3869 </t> 3870 <t> 3871 The field-names given are not limited to the set of standard header 3872 fields defined by this specification. Field names are case-insensitive. 3873 </t> 3874 </section> 3875 </section> 3876 3877 <section title="Authentication Challenges" anchor="response.auth"> 3878 <t> 3879 Authentication challenges indicate what mechanisms are available for the 3880 client to provide authentication credentials in future requests. 3881 </t> 3882 <texttable align="left"> 3883 <ttcol>Header Field Name</ttcol><ttcol>Defined in...</ttcol> 3884 3885 <c>WWW-Authenticate</c> <c>&header-www-authenticate;</c> 3886 <c>Proxy-Authenticate</c> <c>&header-proxy-authenticate;</c> 3887 </texttable> 3888 </section> 3889 3890 <section title="Informative" anchor="response.inform"> 3891 <t> 3892 The remaining response header fields provide more information about 3893 the target resource for potential use in later requests. 3894 </t> 3895 <texttable align="left"> 3896 <ttcol>Header Field Name</ttcol><ttcol>Defined in...</ttcol> 3897 3898 <c>Accept-Ranges</c> <c>&header-accept-ranges;</c> 3899 <c>Allow</c> <c><xref target="header.allow"/></c> 3900 <c>Server</c> <c><xref target="header.server"/></c> 3901 </texttable> 3902 3903 <section title="Allow" anchor="header.allow"> 3904 <iref primary="true" item="Allow header field" x:for-anchor=""/> 3905 <x:anchor-alias value="Allow"/> 3906 <t> 3907 The "Allow" header field lists the set of methods advertised as 3908 supported by the target resource. The purpose of this field is strictly to 3909 inform the recipient of valid request methods associated with the resource. 3910 </t> 3911 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Allow"/> 3912 <x:ref>Allow</x:ref> = #<x:ref>method</x:ref> 3913 </artwork></figure> 3914 <t> 3915 Example of use: 3916 </t> 3917 <figure><artwork type="example"> 3918 Allow: GET, HEAD, PUT 3919 </artwork></figure> 3920 <t> 3921 The actual set of allowed methods is defined by the origin server at the 3922 time of each request. 3923 </t> 3924 <t> 3925 A proxy &MUST-NOT; modify the Allow header field — it does not need to 3926 understand all the methods specified in order to handle them according to 3927 the generic message handling rules. 3928 </t> 3929 </section> 3930 3931 <section title="Server" anchor="header.server"> 3932 <iref primary="true" item="Server header field" x:for-anchor=""/> 3933 <x:anchor-alias value="Server"/> 3934 <t> 3935 The "Server" header field contains information about the 3936 software used by the origin server to handle the request. 3937 </t> 3938 <t> 3939 The field can contain multiple 3940 product tokens (<xref target="product.tokens"/>) and 3941 comments (&header-fields;) identifying the server and any significant 3942 subproducts. The product tokens are listed in order of their significance 3943 for identifying the application. 3944 </t> 3945 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Server"/> 3946 <x:ref>Server</x:ref> = <x:ref>product</x:ref> *( <x:ref>RWS</x:ref> ( <x:ref>product</x:ref> / <x:ref>comment</x:ref> ) ) 3947 </artwork></figure> 3948 <t> 3949 Example: 3950 </t> 3951 <figure><artwork type="example"> 3952 Server: CERN/3.0 libwww/2.17 3953 </artwork></figure> 3954 <t> 3955 If the response is being forwarded through a proxy, the proxy application 3956 &MUST-NOT; modify the <x:ref>Server</x:ref> header field. Instead, it 3957 &MUST; include a <x:ref>Via</x:ref> field (as described in &header-via;). 3958 </t> 3959 <x:note> 3960 <t> 3961 &Note; Revealing the specific software version of the server might 3962 allow the server machine to become more vulnerable to attacks 3963 against software that is known to contain security holes. Server 3964 implementers are encouraged to make this field a configurable 3965 option. 3966 </t> 3967 </x:note> 3968 </section> 3959 3969 </section> 3960 3970 </section>
Note: See TracChangeset
for help on using the changeset viewer.