Changeset 1619 for draft-ietf-httpbis/latest/p2-semantics.xml
- Timestamp:
- 26/03/12 14:44:27 (10 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
draft-ietf-httpbis/latest/p2-semantics.xml
r1618 r1619 311 311 </section> 312 312 313 <section title="Method " anchor="method">313 <section title="Methods" anchor="methods"> 314 314 <x:anchor-alias value="method"/> 315 <x:anchor-alias value="extension-method"/>316 315 <t> 317 316 The method token indicates the request method to be performed on the target … … 336 335 </t> 337 336 338 <section title="Overview of Methods" anchor="overview.of.methods"> 339 <t> 340 The methods listed below are defined in <xref target="method.definitions"/>. 341 </t> 342 <texttable align="left"> 343 <ttcol>Method Name</ttcol><ttcol>Defined in...</ttcol> 344 345 <c>OPTIONS</c> <c><xref target="OPTIONS"/></c> 346 <c>GET</c> <c><xref target="GET"/></c> 347 <c>HEAD</c> <c><xref target="HEAD"/></c> 348 <c>POST</c> <c><xref target="POST"/></c> 349 <c>PUT</c> <c><xref target="PUT"/></c> 350 <c>DELETE</c> <c><xref target="DELETE"/></c> 351 <c>TRACE</c> <c><xref target="TRACE"/></c> 352 <c>CONNECT</c> <c><xref target="CONNECT"/></c> 353 </texttable> 354 <t> 355 Note that this list is not exhaustive — it does not include request methods defined 356 in other specifications. 357 </t> 337 <section title="Safe and Idempotent Methods" anchor="safe.and.idempotent"> 338 339 <section title="Safe Methods" anchor="safe.methods"> 340 <iref item="Safe Methods" primary="true"/> 341 <t> 342 Implementors need to be aware that the software represents the user in 343 their interactions over the Internet, and need to allow 344 the user to be aware of any actions they take which might have an 345 unexpected significance to themselves or others. 346 </t> 347 <t> 348 In particular, the convention has been established that the GET, HEAD, 349 OPTIONS, and TRACE request methods &SHOULD-NOT; have the significance 350 of taking an action other than retrieval. These request methods ought 351 to be considered "<x:dfn anchor="safe">safe</x:dfn>". 352 This allows user agents to represent other methods, such as POST, PUT 353 and DELETE, in a special way, so that the user is made aware of the 354 fact that a possibly unsafe action is being requested. 355 </t> 356 <t> 357 Naturally, it is not possible to ensure that the server does not 358 generate side-effects as a result of performing a GET request; in 359 fact, some dynamic resources consider that a feature. The important 360 distinction here is that the user did not request the side-effects, 361 so therefore cannot be held accountable for them. 362 </t> 363 </section> 364 365 <section title="Idempotent Methods" anchor="idempotent.methods"> 366 <iref item="Idempotent Methods" primary="true"/> 367 <t> 368 Request methods can also have the property of "idempotence" in that, 369 aside from error or expiration issues, the intended effect of multiple 370 identical requests is the same as for a single request. 371 PUT, DELETE, and all safe request methods are idempotent. 372 It is important to note that idempotence refers only to changes 373 requested by the client: a server is free to change its state due 374 to multiple requests for the purpose of tracking those requests, 375 versioning of results, etc. 376 </t> 377 </section> 358 378 </section> 359 379 … … 366 386 Registrations &MUST; include the following fields: 367 387 <list style="symbols"> 368 <t>Method Name (see <xref target="method "/>)</t>388 <t>Method Name (see <xref target="methods"/>)</t> 369 389 <t>Safe ("yes" or "no", see <xref target="safe.methods"/>)</t> 370 390 <t>Pointer to specification text</t> … … 409 429 </t> 410 430 </section> 411 412 </section> 431 </section> 432 433 <section title="Method Definitions" anchor="method.definitions"> 434 435 <section title="OPTIONS" anchor="OPTIONS"> 436 <rdf:Description> 437 <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe> 438 </rdf:Description> 439 <iref primary="true" item="OPTIONS method" x:for-anchor=""/> 440 <iref primary="true" item="Methods" subitem="OPTIONS" x:for-anchor=""/> 441 <t> 442 The OPTIONS method requests information about the 443 communication options available on the request/response chain 444 identified by the effective request URI. This method allows a client to 445 determine the options and/or requirements associated with a resource, 446 or the capabilities of a server, without implying a resource action 447 or initiating a resource retrieval. 448 </t> 449 <t> 450 Responses to the OPTIONS method are not cacheable. 451 </t> 452 <t> 453 If the OPTIONS request includes a message body (as indicated by the 454 presence of Content-Length or Transfer-Encoding), then the media type 455 &MUST; be indicated by a Content-Type field. Although this 456 specification does not define any use for such a body, future 457 extensions to HTTP might use the OPTIONS body to make more detailed 458 queries on the server. 459 </t> 460 <t> 461 If the request-target (&request-target;) is an asterisk ("*"), 462 the OPTIONS request is 463 intended to apply to the server in general rather than to a specific 464 resource. Since a server's communication options typically depend on 465 the resource, the "*" request is only useful as a "ping" or "no-op" 466 type of method; it does nothing beyond allowing the client to test 467 the capabilities of the server. For example, this can be used to test 468 a proxy for HTTP/1.1 conformance (or lack thereof). 469 </t> 470 <t> 471 If the request-target is not an asterisk, the OPTIONS request applies 472 only to the options that are available when communicating with that 473 resource. 474 </t> 475 <t> 476 A 200 response &SHOULD; include any header fields that indicate 477 optional features implemented by the server and applicable to that 478 resource (e.g., Allow), possibly including extensions not defined by 479 this specification. The response body, if any, &SHOULD; also include 480 information about the communication options. The format for such a 481 body is not defined by this specification, but might be defined by 482 future extensions to HTTP. Content negotiation &MAY; be used to select 483 the appropriate response format. If no response body is included, the 484 response &MUST; include a Content-Length field with a field-value of 485 "0". 486 </t> 487 <t> 488 The Max-Forwards header field &MAY; be used to target a 489 specific proxy in the request chain (see <xref target="header.max-forwards"/>). 490 If no Max-Forwards field is present in the request, then the forwarded 491 request &MUST-NOT; include a Max-Forwards field. 492 </t> 493 </section> 494 495 <section title="GET" anchor="GET"> 496 <rdf:Description> 497 <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe> 498 </rdf:Description> 499 <iref primary="true" item="GET method" x:for-anchor=""/> 500 <iref primary="true" item="Methods" subitem="GET" x:for-anchor=""/> 501 <t> 502 The GET method requests transfer of a current representation of 503 the target resource. 504 </t> 505 <t> 506 If the target resource is a data-producing process, it is the 507 produced data which shall be returned as the representation in the response and not 508 the source text of the process, unless that text happens to be the output of 509 the process. 510 </t> 511 <t> 512 The semantics of the GET method change to a "conditional GET" if the 513 request message includes an If-Modified-Since, If-Unmodified-Since, 514 If-Match, If-None-Match, or If-Range header field. A conditional GET 515 requests that the representation be transferred only under the 516 circumstances described by the conditional header field(s). The 517 conditional GET request is intended to reduce unnecessary network 518 usage by allowing cached representations to be refreshed without requiring 519 multiple requests or transferring data already held by the client. 520 </t> 521 <t> 522 The semantics of the GET method change to a "partial GET" if the 523 request message includes a Range header field. A partial GET requests 524 that only part of the representation be transferred, as described in &header-range;. 525 The partial GET request is intended to reduce unnecessary 526 network usage by allowing partially-retrieved representations to be 527 completed without transferring data already held by the client. 528 </t> 529 <t> 530 Bodies on GET requests have no defined semantics. Note that sending a body 531 on a GET request might cause some existing implementations to reject the 532 request. 533 </t> 534 <t> 535 The response to a GET request is cacheable and &MAY; be used to satisfy 536 subsequent GET and HEAD requests (see &caching;). 537 </t> 538 <t> 539 See <xref target="encoding.sensitive.information.in.uris"/> for security considerations when used for forms. 540 </t> 541 </section> 542 543 <section title="HEAD" anchor="HEAD"> 544 <rdf:Description> 545 <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe> 546 </rdf:Description> 547 <iref primary="true" item="HEAD method" x:for-anchor=""/> 548 <iref primary="true" item="Methods" subitem="HEAD" x:for-anchor=""/> 549 <t> 550 The HEAD method is identical to GET except that the server &MUST-NOT; 551 return a message body in the response. The metadata contained 552 in the HTTP header fields in response to a HEAD request &SHOULD; be identical 553 to the information sent in response to a GET request. This method can 554 be used for obtaining metadata about the representation implied by the 555 request without transferring the representation body. This method is 556 often used for testing hypertext links for validity, accessibility, 557 and recent modification. 558 </t> 559 <t> 560 The response to a HEAD request is cacheable and &MAY; be used to satisfy 561 a subsequent HEAD request. It also has potential side effects on 562 previously stored responses to GET; see &p6-head;. 563 </t> 564 <t> 565 Bodies on HEAD requests have no defined semantics. Note that sending a body 566 on a HEAD request might cause some existing implementations to reject the 567 request. 568 </t> 569 </section> 570 571 <section title="POST" anchor="POST"> 572 <iref primary="true" item="POST method" x:for-anchor=""/> 573 <iref primary="true" item="Methods" subitem="POST" x:for-anchor=""/> 574 <t> 575 The POST method requests that the origin server accept the 576 representation enclosed in the request as data to be processed by the 577 target resource. POST is designed to allow a uniform method to cover the 578 following functions: 579 <list style="symbols"> 580 <t> 581 Annotation of existing resources; 582 </t> 583 <t> 584 Posting a message to a bulletin board, newsgroup, mailing list, 585 or similar group of articles; 586 </t> 587 <t> 588 Providing a block of data, such as the result of submitting a 589 form, to a data-handling process; 590 </t> 591 <t> 592 Extending a database through an append operation. 593 </t> 594 </list> 595 </t> 596 <t> 597 The actual function performed by the POST method is determined by the 598 server and is usually dependent on the effective request URI. 599 </t> 600 <t> 601 The action performed by the POST method might not result in a 602 resource that can be identified by a URI. In this case, either 200 603 (OK) or 204 (No Content) is the appropriate response status code, 604 depending on whether or not the response includes a representation that 605 describes the result. 606 </t> 607 <t> 608 If a resource has been created on the origin server, the response 609 &SHOULD; be 201 (Created) and contain a representation which describes the 610 status of the request and refers to the new resource, and a Location 611 header field (see <xref target="header.location"/>). 612 </t> 613 <t> 614 Responses to POST requests are only cacheable when they 615 include explicit freshness information (see &p6-explicit;). A 616 cached POST response with a Content-Location header field 617 (see &header-content-location;) whose value is the effective 618 Request URI &MAY; be used to satisfy subsequent GET and HEAD requests. 619 </t> 620 <t> 621 Note that POST caching is not widely implemented. 622 However, the 303 (See Other) response can be used to direct the 623 user agent to retrieve a cacheable representation of the resource. 624 </t> 625 </section> 626 627 <section title="PUT" anchor="PUT"> 628 <iref primary="true" item="PUT method" x:for-anchor=""/> 629 <iref primary="true" item="Methods" subitem="PUT" x:for-anchor=""/> 630 <t> 631 The PUT method requests that the state of the target resource 632 be created or replaced with the state defined by the representation 633 enclosed in the request message payload. A successful PUT of a given 634 representation would suggest that a subsequent GET on that same target 635 resource will result in an equivalent representation being returned in 636 a 200 (OK) response. However, there is no guarantee that such a state 637 change will be observable, since the target resource might be acted 638 upon by other user agents in parallel, or might be subject to dynamic 639 processing by the origin server, before any subsequent GET is received. 640 A successful response only implies that the user agent's intent was 641 achieved at the time of its processing by the origin server. 642 </t> 643 <t> 644 If the target resource does not have a current representation and 645 the PUT successfully creates one, then the origin server &MUST; inform 646 the user agent by sending a 201 (Created) response. If the target 647 resource does have a current representation and that representation is 648 successfully modified in accordance with the state of the enclosed 649 representation, then either a 200 (OK) or 204 (No Content) response 650 &SHOULD; be sent to indicate successful completion of the request. 651 </t> 652 <t> 653 Unrecognized header fields &SHOULD; be ignored (i.e., not saved 654 as part of the resource state). 655 </t> 656 <t> 657 An origin server &SHOULD; verify that the PUT representation is 658 consistent with any constraints which the server has for the target 659 resource that cannot or will not be changed by the PUT. This is 660 particularly important when the origin server uses internal 661 configuration information related to the URI in order to set the 662 values for representation metadata on GET responses. When a PUT 663 representation is inconsistent with the target resource, the origin 664 server &SHOULD; either make them consistent, by transforming the 665 representation or changing the resource configuration, or respond 666 with an appropriate error message containing sufficient information 667 to explain why the representation is unsuitable. The 409 (Conflict) 668 or 415 (Unsupported Media Type) status codes are suggested, with the 669 latter being specific to constraints on Content-Type values. 670 </t> 671 <t> 672 For example, if the target resource is configured to always have a 673 Content-Type of "text/html" and the representation being PUT has a 674 Content-Type of "image/jpeg", then the origin server &SHOULD; do one of: 675 (a) reconfigure the target resource to reflect the new media type; 676 (b) transform the PUT representation to a format consistent with that 677 of the resource before saving it as the new resource state; or, 678 (c) reject the request with a 415 response indicating that the target 679 resource is limited to "text/html", perhaps including a link to a 680 different resource that would be a suitable target for the new 681 representation. 682 </t> 683 <t> 684 HTTP does not define exactly how a PUT method affects the state 685 of an origin server beyond what can be expressed by the intent of 686 the user agent request and the semantics of the origin server response. 687 It does not define what a resource might be, in any sense of that 688 word, beyond the interface provided via HTTP. It does not define 689 how resource state is "stored", nor how such storage might change 690 as a result of a change in resource state, nor how the origin server 691 translates resource state into representations. Generally speaking, 692 all implementation details behind the resource interface are 693 intentionally hidden by the server. 694 </t> 695 <t> 696 The fundamental difference between the POST and PUT methods is 697 highlighted by the different intent for the target resource. 698 The target resource in a POST request is intended to handle the 699 enclosed representation as a data-accepting process, such as for 700 a gateway to some other protocol or a document that accepts annotations. 701 In contrast, the target resource in a PUT request is intended to 702 take the enclosed representation as a new or replacement value. 703 Hence, the intent of PUT is idempotent and visible to intermediaries, 704 even though the exact effect is only known by the origin server. 705 </t> 706 <t> 707 Proper interpretation of a PUT request presumes that the user agent 708 knows what target resource is desired. A service that is intended 709 to select a proper URI on behalf of the client, after receiving 710 a state-changing request, &SHOULD; be implemented using the POST 711 method rather than PUT. If the origin server will not make the 712 requested PUT state change to the target resource and instead 713 wishes to have it applied to a different resource, such as when the 714 resource has been moved to a different URI, then the origin server 715 &MUST; send a 301 (Moved Permanently) response; the user agent &MAY; 716 then make its own decision regarding whether or not to redirect the 717 request. 718 </t> 719 <t> 720 A PUT request applied to the target resource &MAY; have side-effects 721 on other resources. For example, an article might have a URI for 722 identifying "the current version" (a resource) which is separate 723 from the URIs identifying each particular version (different 724 resources that at one point shared the same state as the current version 725 resource). A successful PUT request on "the current version" URI might 726 therefore create a new version resource in addition to changing the 727 state of the target resource, and might also cause links to be added 728 between the related resources. 729 </t> 730 <t> 731 An origin server &SHOULD; reject any PUT request that contains a 732 Content-Range header field, since it might be misinterpreted as 733 partial content (or might be partial content that is being mistakenly 734 PUT as a full representation). Partial content updates are 735 possible by targeting a separately identified resource with state 736 that overlaps a portion of the larger resource, or by using a 737 different method that has been specifically defined for partial 738 updates (for example, the PATCH method defined in 739 <xref target="RFC5789"/>). 740 </t> 741 <t> 742 Responses to the PUT method are not cacheable. If a PUT request passes 743 through a cache that has one or more stored responses for the effective 744 request URI, those stored responses will be invalidated (see 745 &p6-invalid;). 746 </t> 747 </section> 748 749 <section title="DELETE" anchor="DELETE"> 750 <iref primary="true" item="DELETE method" x:for-anchor=""/> 751 <iref primary="true" item="Methods" subitem="DELETE" x:for-anchor=""/> 752 <t> 753 The DELETE method requests that the origin server delete the target 754 resource. This method &MAY; be overridden by 755 human intervention (or other means) on the origin server. The client cannot 756 be guaranteed that the operation has been carried out, even if the 757 status code returned from the origin server indicates that the action 758 has been completed successfully. However, the server &SHOULD-NOT; 759 indicate success unless, at the time the response is given, it 760 intends to delete the resource or move it to an inaccessible 761 location. 762 </t> 763 <t> 764 A successful response &SHOULD; be 200 (OK) if the response includes an 765 representation describing the status, 202 (Accepted) if the action has not 766 yet been enacted, or 204 (No Content) if the action has been enacted 767 but the response does not include a representation. 768 </t> 769 <t> 770 Bodies on DELETE requests have no defined semantics. Note that sending a body 771 on a DELETE request might cause some existing implementations to reject the 772 request. 773 </t> 774 <t> 775 Responses to the DELETE method are not cacheable. If a DELETE request 776 passes through a cache that has one or more stored responses for the 777 effective request URI, those stored responses will be invalidated (see 778 &p6-invalid;). 779 </t> 780 </section> 781 782 <section title="TRACE" anchor="TRACE"> 783 <rdf:Description> 784 <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe> 785 </rdf:Description> 786 <iref primary="true" item="TRACE method" x:for-anchor=""/> 787 <iref primary="true" item="Methods" subitem="TRACE" x:for-anchor=""/> 788 <t> 789 The TRACE method requests a remote, application-layer loop-back 790 of the request message. The final recipient of the request 791 &SHOULD; reflect the message received back to the client as the 792 message body of a 200 (OK) response. The final recipient is either the 793 origin server or the first proxy to receive a Max-Forwards 794 value of zero (0) in the request (see <xref target="header.max-forwards"/>). 795 A TRACE request &MUST-NOT; include a message body. 796 </t> 797 <t> 798 TRACE allows the client to see what is being received at the other 799 end of the request chain and use that data for testing or diagnostic 800 information. The value of the Via header field (&header-via;) is of 801 particular interest, since it acts as a trace of the request chain. 802 Use of the Max-Forwards header field allows the client to limit the 803 length of the request chain, which is useful for testing a chain of 804 proxies forwarding messages in an infinite loop. 805 </t> 806 <t> 807 If the request is valid, the response &SHOULD; have a Content-Type of 808 "message/http" (see &media-type-message-http;) and contain a message body 809 that encloses a copy of the entire request message. 810 Responses to the TRACE method are not cacheable. 811 </t> 812 </section> 813 814 <section title="CONNECT" anchor="CONNECT"> 815 <iref primary="true" item="CONNECT method" x:for-anchor=""/> 816 <iref primary="true" item="Methods" subitem="CONNECT" x:for-anchor=""/> 817 <t> 818 The CONNECT method requests that the proxy establish a tunnel 819 to the request-target and, if successful, thereafter restrict its behavior 820 to blind forwarding of packets until the connection is closed. 821 </t> 822 <t> 823 When using CONNECT, the request-target &MUST; use the authority form 824 (&request-target;); i.e., the request-target consists of only the 825 host name and port number of the tunnel destination, separated by a colon. 826 For example, 827 </t> 828 <figure><artwork type="message/http; msgtype="request"" x:indent-with=" "> 829 CONNECT server.example.com:80 HTTP/1.1 830 Host: server.example.com:80 831 832 </artwork></figure> 833 <t> 834 Any successful (2xx) response to a CONNECT request indicates that the 835 proxy has established a connection to the requested host and port, 836 and has switched to tunneling the current connection to that server 837 connection. 838 The tunneled data from the server begins immediately after the blank line 839 that concludes the successful response's header block. 840 A server &SHOULD-NOT; send any Transfer-Encoding or Content-Length 841 header fields in a successful response. 842 A client &MUST; ignore any Content-Length or Transfer-Encoding header 843 fields received in a successful response. 844 </t> 845 <t> 846 Any response other than a successful response indicates that the tunnel 847 has not yet been formed and that the connection remains governed by HTTP. 848 </t> 849 <t> 850 Proxy authentication might be used to establish the 851 authority to create a tunnel: 852 </t> 853 <figure><artwork type="message/http; msgtype="request"" x:indent-with=" "> 854 CONNECT server.example.com:80 HTTP/1.1 855 Host: server.example.com:80 856 Proxy-Authorization: basic aGVsbG86d29ybGQ= 857 858 </artwork></figure> 859 <t> 860 A message body on a CONNECT request has no defined semantics. Sending a 861 body on a CONNECT request might cause existing implementations to reject 862 the request. 863 </t> 864 <t> 865 Similar to a pipelined HTTP/1.1 request, data to be tunneled from client 866 to server &MAY; be sent immediately after the request (before a response 867 is received). The usual caveats also apply: 868 data may be discarded if the eventual response is negative, and the 869 connection may be reset with no response if more than one TCP segment 870 is outstanding. 871 </t> 872 <t> 873 It may be the case that the proxy itself can only reach the requested 874 origin server through another proxy. In this case, the first proxy 875 &SHOULD; make a CONNECT request of that next proxy, requesting a tunnel 876 to the authority. A proxy &MUST-NOT; respond with any 2xx status code 877 unless it has either a direct or tunnel connection established to the 878 authority. 879 </t> 880 <t> 881 If at any point either one of the peers gets disconnected, any 882 outstanding data that came from that peer will be passed to the other 883 one, and after that also the other connection will be terminated by 884 the proxy. If there is outstanding data to that peer undelivered, 885 that data will be discarded. 886 </t> 887 <t> 888 An origin server which receives a CONNECT request for itself &MAY; 889 respond with a 2xx status code to indicate that a connection is 890 established. However, most origin servers do not implement CONNECT. 891 </t> 892 </section> 893 </section> 894 413 895 </section> 414 896 … … 1636 2118 1637 2119 1638 <section title="Method Definitions" anchor="method.definitions">1639 <t>1640 The set of common request methods for HTTP/1.1 is defined below. Although1641 this set can be expanded, additional methods cannot be assumed to1642 share the same semantics for separately extended clients and servers.1643 </t>1644 1645 <section title="Safe and Idempotent Methods" anchor="safe.and.idempotent">1646 1647 <section title="Safe Methods" anchor="safe.methods">1648 <iref item="Safe Methods" primary="true"/>1649 <t>1650 Implementors need to be aware that the software represents the user in1651 their interactions over the Internet, and need to allow1652 the user to be aware of any actions they take which might have an1653 unexpected significance to themselves or others.1654 </t>1655 <t>1656 In particular, the convention has been established that the GET, HEAD,1657 OPTIONS, and TRACE request methods &SHOULD-NOT; have the significance1658 of taking an action other than retrieval. These request methods ought1659 to be considered "<x:dfn anchor="safe">safe</x:dfn>".1660 This allows user agents to represent other methods, such as POST, PUT1661 and DELETE, in a special way, so that the user is made aware of the1662 fact that a possibly unsafe action is being requested.1663 </t>1664 <t>1665 Naturally, it is not possible to ensure that the server does not1666 generate side-effects as a result of performing a GET request; in1667 fact, some dynamic resources consider that a feature. The important1668 distinction here is that the user did not request the side-effects,1669 so therefore cannot be held accountable for them.1670 </t>1671 </section>1672 1673 <section title="Idempotent Methods" anchor="idempotent.methods">1674 <iref item="Idempotent Methods" primary="true"/>1675 <t>1676 Request methods can also have the property of "idempotence" in that,1677 aside from error or expiration issues, the intended effect of multiple1678 identical requests is the same as for a single request.1679 PUT, DELETE, and all safe request methods are idempotent.1680 It is important to note that idempotence refers only to changes1681 requested by the client: a server is free to change its state due1682 to multiple requests for the purpose of tracking those requests,1683 versioning of results, etc.1684 </t>1685 </section>1686 </section>1687 1688 <section title="OPTIONS" anchor="OPTIONS">1689 <rdf:Description>1690 <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>1691 </rdf:Description>1692 <iref primary="true" item="OPTIONS method" x:for-anchor=""/>1693 <iref primary="true" item="Methods" subitem="OPTIONS" x:for-anchor=""/>1694 <t>1695 The OPTIONS method requests information about the1696 communication options available on the request/response chain1697 identified by the effective request URI. This method allows a client to1698 determine the options and/or requirements associated with a resource,1699 or the capabilities of a server, without implying a resource action1700 or initiating a resource retrieval.1701 </t>1702 <t>1703 Responses to the OPTIONS method are not cacheable.1704 </t>1705 <t>1706 If the OPTIONS request includes a message body (as indicated by the1707 presence of Content-Length or Transfer-Encoding), then the media type1708 &MUST; be indicated by a Content-Type field. Although this1709 specification does not define any use for such a body, future1710 extensions to HTTP might use the OPTIONS body to make more detailed1711 queries on the server.1712 </t>1713 <t>1714 If the request-target (&request-target;) is an asterisk ("*"),1715 the OPTIONS request is1716 intended to apply to the server in general rather than to a specific1717 resource. Since a server's communication options typically depend on1718 the resource, the "*" request is only useful as a "ping" or "no-op"1719 type of method; it does nothing beyond allowing the client to test1720 the capabilities of the server. For example, this can be used to test1721 a proxy for HTTP/1.1 conformance (or lack thereof).1722 </t>1723 <t>1724 If the request-target is not an asterisk, the OPTIONS request applies1725 only to the options that are available when communicating with that1726 resource.1727 </t>1728 <t>1729 A 200 response &SHOULD; include any header fields that indicate1730 optional features implemented by the server and applicable to that1731 resource (e.g., Allow), possibly including extensions not defined by1732 this specification. The response body, if any, &SHOULD; also include1733 information about the communication options. The format for such a1734 body is not defined by this specification, but might be defined by1735 future extensions to HTTP. Content negotiation &MAY; be used to select1736 the appropriate response format. If no response body is included, the1737 response &MUST; include a Content-Length field with a field-value of1738 "0".1739 </t>1740 <t>1741 The Max-Forwards header field &MAY; be used to target a1742 specific proxy in the request chain (see <xref target="header.max-forwards"/>).1743 If no Max-Forwards field is present in the request, then the forwarded1744 request &MUST-NOT; include a Max-Forwards field.1745 </t>1746 </section>1747 1748 <section title="GET" anchor="GET">1749 <rdf:Description>1750 <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>1751 </rdf:Description>1752 <iref primary="true" item="GET method" x:for-anchor=""/>1753 <iref primary="true" item="Methods" subitem="GET" x:for-anchor=""/>1754 <t>1755 The GET method requests transfer of a current representation of1756 the target resource.1757 </t>1758 <t>1759 If the target resource is a data-producing process, it is the1760 produced data which shall be returned as the representation in the response and not1761 the source text of the process, unless that text happens to be the output of1762 the process.1763 </t>1764 <t>1765 The semantics of the GET method change to a "conditional GET" if the1766 request message includes an If-Modified-Since, If-Unmodified-Since,1767 If-Match, If-None-Match, or If-Range header field. A conditional GET1768 requests that the representation be transferred only under the1769 circumstances described by the conditional header field(s). The1770 conditional GET request is intended to reduce unnecessary network1771 usage by allowing cached representations to be refreshed without requiring1772 multiple requests or transferring data already held by the client.1773 </t>1774 <t>1775 The semantics of the GET method change to a "partial GET" if the1776 request message includes a Range header field. A partial GET requests1777 that only part of the representation be transferred, as described in &header-range;.1778 The partial GET request is intended to reduce unnecessary1779 network usage by allowing partially-retrieved representations to be1780 completed without transferring data already held by the client.1781 </t>1782 <t>1783 Bodies on GET requests have no defined semantics. Note that sending a body1784 on a GET request might cause some existing implementations to reject the1785 request.1786 </t>1787 <t>1788 The response to a GET request is cacheable and &MAY; be used to satisfy1789 subsequent GET and HEAD requests (see &caching;).1790 </t>1791 <t>1792 See <xref target="encoding.sensitive.information.in.uris"/> for security considerations when used for forms.1793 </t>1794 </section>1795 1796 <section title="HEAD" anchor="HEAD">1797 <rdf:Description>1798 <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>1799 </rdf:Description>1800 <iref primary="true" item="HEAD method" x:for-anchor=""/>1801 <iref primary="true" item="Methods" subitem="HEAD" x:for-anchor=""/>1802 <t>1803 The HEAD method is identical to GET except that the server &MUST-NOT;1804 return a message body in the response. The metadata contained1805 in the HTTP header fields in response to a HEAD request &SHOULD; be identical1806 to the information sent in response to a GET request. This method can1807 be used for obtaining metadata about the representation implied by the1808 request without transferring the representation body. This method is1809 often used for testing hypertext links for validity, accessibility,1810 and recent modification.1811 </t>1812 <t>1813 The response to a HEAD request is cacheable and &MAY; be used to satisfy1814 a subsequent HEAD request. It also has potential side effects on1815 previously stored responses to GET; see &p6-head;.1816 </t>1817 <t>1818 Bodies on HEAD requests have no defined semantics. Note that sending a body1819 on a HEAD request might cause some existing implementations to reject the1820 request.1821 </t>1822 </section>1823 1824 <section title="POST" anchor="POST">1825 <iref primary="true" item="POST method" x:for-anchor=""/>1826 <iref primary="true" item="Methods" subitem="POST" x:for-anchor=""/>1827 <t>1828 The POST method requests that the origin server accept the1829 representation enclosed in the request as data to be processed by the1830 target resource. POST is designed to allow a uniform method to cover the1831 following functions:1832 <list style="symbols">1833 <t>1834 Annotation of existing resources;1835 </t>1836 <t>1837 Posting a message to a bulletin board, newsgroup, mailing list,1838 or similar group of articles;1839 </t>1840 <t>1841 Providing a block of data, such as the result of submitting a1842 form, to a data-handling process;1843 </t>1844 <t>1845 Extending a database through an append operation.1846 </t>1847 </list>1848 </t>1849 <t>1850 The actual function performed by the POST method is determined by the1851 server and is usually dependent on the effective request URI.1852 </t>1853 <t>1854 The action performed by the POST method might not result in a1855 resource that can be identified by a URI. In this case, either 2001856 (OK) or 204 (No Content) is the appropriate response status code,1857 depending on whether or not the response includes a representation that1858 describes the result.1859 </t>1860 <t>1861 If a resource has been created on the origin server, the response1862 &SHOULD; be 201 (Created) and contain a representation which describes the1863 status of the request and refers to the new resource, and a Location1864 header field (see <xref target="header.location"/>).1865 </t>1866 <t>1867 Responses to POST requests are only cacheable when they1868 include explicit freshness information (see &p6-explicit;). A1869 cached POST response with a Content-Location header field1870 (see &header-content-location;) whose value is the effective1871 Request URI &MAY; be used to satisfy subsequent GET and HEAD requests.1872 </t>1873 <t>1874 Note that POST caching is not widely implemented.1875 However, the 303 (See Other) response can be used to direct the1876 user agent to retrieve a cacheable representation of the resource.1877 </t>1878 </section>1879 1880 <section title="PUT" anchor="PUT">1881 <iref primary="true" item="PUT method" x:for-anchor=""/>1882 <iref primary="true" item="Methods" subitem="PUT" x:for-anchor=""/>1883 <t>1884 The PUT method requests that the state of the target resource1885 be created or replaced with the state defined by the representation1886 enclosed in the request message payload. A successful PUT of a given1887 representation would suggest that a subsequent GET on that same target1888 resource will result in an equivalent representation being returned in1889 a 200 (OK) response. However, there is no guarantee that such a state1890 change will be observable, since the target resource might be acted1891 upon by other user agents in parallel, or might be subject to dynamic1892 processing by the origin server, before any subsequent GET is received.1893 A successful response only implies that the user agent's intent was1894 achieved at the time of its processing by the origin server.1895 </t>1896 <t>1897 If the target resource does not have a current representation and1898 the PUT successfully creates one, then the origin server &MUST; inform1899 the user agent by sending a 201 (Created) response. If the target1900 resource does have a current representation and that representation is1901 successfully modified in accordance with the state of the enclosed1902 representation, then either a 200 (OK) or 204 (No Content) response1903 &SHOULD; be sent to indicate successful completion of the request.1904 </t>1905 <t>1906 Unrecognized header fields &SHOULD; be ignored (i.e., not saved1907 as part of the resource state).1908 </t>1909 <t>1910 An origin server &SHOULD; verify that the PUT representation is1911 consistent with any constraints which the server has for the target1912 resource that cannot or will not be changed by the PUT. This is1913 particularly important when the origin server uses internal1914 configuration information related to the URI in order to set the1915 values for representation metadata on GET responses. When a PUT1916 representation is inconsistent with the target resource, the origin1917 server &SHOULD; either make them consistent, by transforming the1918 representation or changing the resource configuration, or respond1919 with an appropriate error message containing sufficient information1920 to explain why the representation is unsuitable. The 409 (Conflict)1921 or 415 (Unsupported Media Type) status codes are suggested, with the1922 latter being specific to constraints on Content-Type values.1923 </t>1924 <t>1925 For example, if the target resource is configured to always have a1926 Content-Type of "text/html" and the representation being PUT has a1927 Content-Type of "image/jpeg", then the origin server &SHOULD; do one of:1928 (a) reconfigure the target resource to reflect the new media type;1929 (b) transform the PUT representation to a format consistent with that1930 of the resource before saving it as the new resource state; or,1931 (c) reject the request with a 415 response indicating that the target1932 resource is limited to "text/html", perhaps including a link to a1933 different resource that would be a suitable target for the new1934 representation.1935 </t>1936 <t>1937 HTTP does not define exactly how a PUT method affects the state1938 of an origin server beyond what can be expressed by the intent of1939 the user agent request and the semantics of the origin server response.1940 It does not define what a resource might be, in any sense of that1941 word, beyond the interface provided via HTTP. It does not define1942 how resource state is "stored", nor how such storage might change1943 as a result of a change in resource state, nor how the origin server1944 translates resource state into representations. Generally speaking,1945 all implementation details behind the resource interface are1946 intentionally hidden by the server.1947 </t>1948 <t>1949 The fundamental difference between the POST and PUT methods is1950 highlighted by the different intent for the target resource.1951 The target resource in a POST request is intended to handle the1952 enclosed representation as a data-accepting process, such as for1953 a gateway to some other protocol or a document that accepts annotations.1954 In contrast, the target resource in a PUT request is intended to1955 take the enclosed representation as a new or replacement value.1956 Hence, the intent of PUT is idempotent and visible to intermediaries,1957 even though the exact effect is only known by the origin server.1958 </t>1959 <t>1960 Proper interpretation of a PUT request presumes that the user agent1961 knows what target resource is desired. A service that is intended1962 to select a proper URI on behalf of the client, after receiving1963 a state-changing request, &SHOULD; be implemented using the POST1964 method rather than PUT. If the origin server will not make the1965 requested PUT state change to the target resource and instead1966 wishes to have it applied to a different resource, such as when the1967 resource has been moved to a different URI, then the origin server1968 &MUST; send a 301 (Moved Permanently) response; the user agent &MAY;1969 then make its own decision regarding whether or not to redirect the1970 request.1971 </t>1972 <t>1973 A PUT request applied to the target resource &MAY; have side-effects1974 on other resources. For example, an article might have a URI for1975 identifying "the current version" (a resource) which is separate1976 from the URIs identifying each particular version (different1977 resources that at one point shared the same state as the current version1978 resource). A successful PUT request on "the current version" URI might1979 therefore create a new version resource in addition to changing the1980 state of the target resource, and might also cause links to be added1981 between the related resources.1982 </t>1983 <t>1984 An origin server &SHOULD; reject any PUT request that contains a1985 Content-Range header field, since it might be misinterpreted as1986 partial content (or might be partial content that is being mistakenly1987 PUT as a full representation). Partial content updates are1988 possible by targeting a separately identified resource with state1989 that overlaps a portion of the larger resource, or by using a1990 different method that has been specifically defined for partial1991 updates (for example, the PATCH method defined in1992 <xref target="RFC5789"/>).1993 </t>1994 <t>1995 Responses to the PUT method are not cacheable. If a PUT request passes1996 through a cache that has one or more stored responses for the effective1997 request URI, those stored responses will be invalidated (see1998 &p6-invalid;).1999 </t>2000 </section>2001 2002 <section title="DELETE" anchor="DELETE">2003 <iref primary="true" item="DELETE method" x:for-anchor=""/>2004 <iref primary="true" item="Methods" subitem="DELETE" x:for-anchor=""/>2005 <t>2006 The DELETE method requests that the origin server delete the target2007 resource. This method &MAY; be overridden by2008 human intervention (or other means) on the origin server. The client cannot2009 be guaranteed that the operation has been carried out, even if the2010 status code returned from the origin server indicates that the action2011 has been completed successfully. However, the server &SHOULD-NOT;2012 indicate success unless, at the time the response is given, it2013 intends to delete the resource or move it to an inaccessible2014 location.2015 </t>2016 <t>2017 A successful response &SHOULD; be 200 (OK) if the response includes an2018 representation describing the status, 202 (Accepted) if the action has not2019 yet been enacted, or 204 (No Content) if the action has been enacted2020 but the response does not include a representation.2021 </t>2022 <t>2023 Bodies on DELETE requests have no defined semantics. Note that sending a body2024 on a DELETE request might cause some existing implementations to reject the2025 request.2026 </t>2027 <t>2028 Responses to the DELETE method are not cacheable. If a DELETE request2029 passes through a cache that has one or more stored responses for the2030 effective request URI, those stored responses will be invalidated (see2031 &p6-invalid;).2032 </t>2033 </section>2034 2035 <section title="TRACE" anchor="TRACE">2036 <rdf:Description>2037 <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>2038 </rdf:Description>2039 <iref primary="true" item="TRACE method" x:for-anchor=""/>2040 <iref primary="true" item="Methods" subitem="TRACE" x:for-anchor=""/>2041 <t>2042 The TRACE method requests a remote, application-layer loop-back2043 of the request message. The final recipient of the request2044 &SHOULD; reflect the message received back to the client as the2045 message body of a 200 (OK) response. The final recipient is either the2046 origin server or the first proxy to receive a Max-Forwards2047 value of zero (0) in the request (see <xref target="header.max-forwards"/>).2048 A TRACE request &MUST-NOT; include a message body.2049 </t>2050 <t>2051 TRACE allows the client to see what is being received at the other2052 end of the request chain and use that data for testing or diagnostic2053 information. The value of the Via header field (&header-via;) is of2054 particular interest, since it acts as a trace of the request chain.2055 Use of the Max-Forwards header field allows the client to limit the2056 length of the request chain, which is useful for testing a chain of2057 proxies forwarding messages in an infinite loop.2058 </t>2059 <t>2060 If the request is valid, the response &SHOULD; have a Content-Type of2061 "message/http" (see &media-type-message-http;) and contain a message body2062 that encloses a copy of the entire request message.2063 Responses to the TRACE method are not cacheable.2064 </t>2065 </section>2066 2067 <section title="CONNECT" anchor="CONNECT">2068 <iref primary="true" item="CONNECT method" x:for-anchor=""/>2069 <iref primary="true" item="Methods" subitem="CONNECT" x:for-anchor=""/>2070 <t>2071 The CONNECT method requests that the proxy establish a tunnel2072 to the request-target and, if successful, thereafter restrict its behavior2073 to blind forwarding of packets until the connection is closed.2074 </t>2075 <t>2076 When using CONNECT, the request-target &MUST; use the authority form2077 (&request-target;); i.e., the request-target consists of only the2078 host name and port number of the tunnel destination, separated by a colon.2079 For example,2080 </t>2081 <figure><artwork type="message/http; msgtype="request"" x:indent-with=" ">2082 CONNECT server.example.com:80 HTTP/1.12083 Host: server.example.com:802084 2085 </artwork></figure>2086 <t>2087 Any successful (2xx) response to a CONNECT request indicates that the2088 proxy has established a connection to the requested host and port,2089 and has switched to tunneling the current connection to that server2090 connection.2091 The tunneled data from the server begins immediately after the blank line2092 that concludes the successful response's header block.2093 A server &SHOULD-NOT; send any Transfer-Encoding or Content-Length2094 header fields in a successful response.2095 A client &MUST; ignore any Content-Length or Transfer-Encoding header2096 fields received in a successful response.2097 </t>2098 <t>2099 Any response other than a successful response indicates that the tunnel2100 has not yet been formed and that the connection remains governed by HTTP.2101 </t>2102 <t>2103 Proxy authentication might be used to establish the2104 authority to create a tunnel:2105 </t>2106 <figure><artwork type="message/http; msgtype="request"" x:indent-with=" ">2107 CONNECT server.example.com:80 HTTP/1.12108 Host: server.example.com:802109 Proxy-Authorization: basic aGVsbG86d29ybGQ=2110 2111 </artwork></figure>2112 <t>2113 A message body on a CONNECT request has no defined semantics. Sending a2114 body on a CONNECT request might cause existing implementations to reject2115 the request.2116 </t>2117 <t>2118 Similar to a pipelined HTTP/1.1 request, data to be tunneled from client2119 to server &MAY; be sent immediately after the request (before a response2120 is received). The usual caveats also apply:2121 data may be discarded if the eventual response is negative, and the2122 connection may be reset with no response if more than one TCP segment2123 is outstanding.2124 </t>2125 <t>2126 It may be the case that the proxy itself can only reach the requested2127 origin server through another proxy. In this case, the first proxy2128 &SHOULD; make a CONNECT request of that next proxy, requesting a tunnel2129 to the authority. A proxy &MUST-NOT; respond with any 2xx status code2130 unless it has either a direct or tunnel connection established to the2131 authority.2132 </t>2133 <t>2134 If at any point either one of the peers gets disconnected, any2135 outstanding data that came from that peer will be passed to the other2136 one, and after that also the other connection will be terminated by2137 the proxy. If there is outstanding data to that peer undelivered,2138 that data will be discarded.2139 </t>2140 <t>2141 An origin server which receives a CONNECT request for itself &MAY;2142 respond with a 2xx status code to indicate that a connection is2143 established. However, most origin servers do not implement CONNECT.2144 </t>2145 </section>2146 </section>2147 2148 2120 <section title="Common Protocol Parameters" anchor="common.protocol.parameters"> 2149 2121 <section title="Date/Time Formats" anchor="http.date"> … … 3679 3651 <section title="Changes from RFC 2616" anchor="changes.from.rfc.2616"> 3680 3652 <t> 3653 Clarify definition of POST. 3654 (<xref target="POST"/>) 3655 </t> 3656 <t> 3657 Remove requirement to handle all Content-* header fields; ban use of 3658 Content-Range with PUT. 3659 (<xref target="PUT"/>) 3660 </t> 3661 <t> 3662 Take over definition of CONNECT method from <xref target="RFC2817"/>. 3663 (<xref target="CONNECT"/>) 3664 </t> 3665 <t> 3681 3666 This document takes over the Status Code Registry, previously defined 3682 3667 in <xref target="RFC2817" x:fmt="of" x:sec="7.1"/>. … … 3714 3699 <xref target="RFC2817"/>). 3715 3700 (<xref target="status.426"/>) 3716 </t>3717 <t>3718 Clarify definition of POST.3719 (<xref target="POST"/>)3720 </t>3721 <t>3722 Remove requirement to handle all Content-* header fields; ban use of3723 Content-Range with PUT.3724 (<xref target="PUT"/>)3725 </t>3726 <t>3727 Take over definition of CONNECT method from <xref target="RFC2817"/>.3728 (<xref target="CONNECT"/>)3729 3701 </t> 3730 3702 <t>
Note: See TracChangeset
for help on using the changeset viewer.