The HTTP BUTT Method

Internet-Draft	The HTTP BUTT Method	October 2022
Andrews	Expires 1 April 2023	[Page]

Status of This Memo

This Internet-Draft is (not actually) submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts (such as, in this case, some rando with a GitHub Pages site). The list of current Internet-Drafts (which will not include this document) is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 1 April 2023.¶

Copyright Notice

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶

1. Introduction

This specification defines the HTTP BUTT request method as a means of bypassing the abstraction that is the entire point of RESTful systems, and interacting with a resource's back-end directly.¶

Potential applications include SOAP, GraphQL or anything else that pipes its entire innards directly through a single method on a single endpoint.¶

1.1. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. These words may also appear in this document in lower case as plain English words, absent their normative meanings.¶

2. The BUTT Method

The BUTT method tunnels back-end-resource-specific communication through HTTP, without pretense of abstraction.¶

While HTTP's POST method allows essentially arbitrary actions already, it was still created in the context of HTTP's resource abstraction. Some uses of POST do implement a resource interface at a suitable level of abstraction. However, many simply tunnel a completely separate interface using HTTP as a transport layer.¶

The HTTP ecosystem will benefit from expicitly distinguishing these two usages. Using HTTP BUTT makes it clear that the violation of resource abstraction is fully intentional, and only the exposed nature of the back-end is important to any interactions.¶

BUTT /database HTTP/1.1
Host: example.org
Content-Length: 27
Content-Type: application/sql

DROP TABLE important_table;

Figure 1: A typical usage of a BUTT request.

The BUTT method is neither safe nor idempotent. Both client and server are advised to guard against unwanted effects that could result from BUTT access, as documented by the back-end resource in question.¶

2.1. Caching and HTTP intermediaries

Responses to BUTT requests are never cacheable. Resources implementing the BUTT method are acknowledging that they are either uncacheable, or expect to implement a completely separate caching system after disregarding that of HTTP.¶

If a BUTT request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale.¶

Similarly, ETags and associated headers MUST NOT be relied upon to manage collisions or otherwise keep track of resource state for BUTT requests, and are likely to be unreliable for any HTTP interaction with a resource once a BUTT request has been received. The back-end is assumed to define its own mechanism for ETag-like functionality, if any¶

In general, intermediaries as defined in [RFC9110], Section 3.7 MUST NOT interfere with client-to-back-end BUTT communication in any way not explictly required by this specification, regardless of the intended benefits of HTTP as supported by intermediaries.¶

3. The Accept-Butt Header

This specification introduces a new response header field Accept-Butt used to specify the document formats accepted by the server in HTTP BUTT requests. Accept-Butt SHOULD appear in the OPTIONS response for any resource that supports the use of the BUTT method. The presence of the Accept-Butt header in response to any method is an implicit indication that BUTT is allowed on the resource identified by the Request-URI. The presence of a specific document format in this header indicates that this specific format is allowed on the resource identified by the Request-URI.¶

The syntax for Accept-Butt headers, using the ABNF [RFC5234] syntax defined in [RFC9110], Section 12.5.1, is given by the following definition:¶

    Accept-Butt = #media-range
    Accept-Butt =/ "false"

The Accept-Butt header specifies a media range as defined by HTTP [RFC9110]. The media range specifies a type of representation that can be BUTTed to the Request-URI.¶

Accept-Butt can also be set to the string "false", indicating that the back-end in question does not allow input in the form of a request body. However, if BUTT is also present in the Allow header, this indicates that the back-end MAY answer BUTT requests that do not include a request body with output.¶

4. Status Codes for BUTT Responses

This specification introduces the following response codes to handle response semantics unique to the BUTT method.¶

4.1. 255 Expulsive

The 255 (Expulsive) status code indicates that the back-end has chosen to return more information than was requested. The requested information MUST be present in the response. However, the location of the requested information within the larger response body, as well as the syntax and semantics of the additional information, is back-end-defined.¶

While technically a successful result, it is RECOMMENDED to notify the system administrator that some form of tuning or maintenance might be in order.¶

4.2. 455 Inadequate Preparation

The 455 (Inadequate Preparation) status code indicates that a BUTT request with a request body was made, and that despite the request body having an acceptable Content-Type, the back-end resource was not properly prepared to act on the given input. Back-ends SHOULD respond with information on what preparation is needed prior to re-trying the request, using an appropriate media type such as [RFC7807] HTTP Problem Details.¶

4.3. 555 Retentive

The 555 (Retentive) status code indicates that the back-end is refusing to respond as requested. No additional information is expected with this response, as the back-end may not be aware of the unconscious factors leading to the repressive state. It is RECOMMENDED to contact the system administrator to arrange appropriate therapy.¶

7. IANA Considerations

7.1. Method Registration

IANA has updated the "Hypertext Transfer Protocol (HTTP) Method Registry" at <https://www.iana.org/assignments/http-methods> with the registration procedure of [RFC9110], Section 16.1.1 and the method names summarized in the following table.¶

Table 1
Method	Safe	Idempotent	Section
BUTT	no	no	Section 2

7.2. Status Code Registration

IANA has updated the "Hypertext Transfer Protocol (HTTP) Status Code Registry" at <https://www.iana.org/assignments/http-status-codes> with the registration procedure of [RFC9110], Section 16.2.1 and the status code values summarized in the following table.¶

Table 2
Value	Description	Section
255	Expulsive	Section 4.1
455	Inadequate Preparation	Section 4.2
555	Retentive	Section 4.3

7.3. Field Name Registration

IANA has updated the "Hypertext Transfer Protocol (HTTP) Field Name Registry" at <https://www.iana.org/assignments/http-fields with the registration procedure of [RFC9110], Section 16.3.1 and the field names listed in the following table.¶

Table 3
Field Name	Status	Section
Accept-Butt	permanent	{#accept-butt}

8. References

8.1. Normative References

[RFC2119]: Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174]: Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC9110]: Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, <https://www.rfc-editor.org/rfc/rfc9110>.

8.2. Informative References

[I-D.ietf-httpbis-safe-method-w-body]: Reschke, J., Malhotra, A., and J. M. Snell, "The HTTP QUERY Method", Work in Progress, Internet-Draft, draft-ietf-httpbis-safe-method-w-body-03, 4 July 2022, <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-safe-method-w-body-03>.
[I-D.wilde-accept-post]: Arwe, J., Speicher, S., and E. Wilde, "The Accept-Post HTTP Header", Work in Progress, Internet-Draft, draft-wilde-accept-post-03, 5 August 2014, <https://datatracker.ietf.org/doc/html/draft-wilde-accept-post-03>.
[RFC5234]: Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, <https://www.rfc-editor.org/rfc/rfc5234>.
[RFC7807]: Nottingham, M. and E. Wilde, "Problem Details for HTTP APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, <https://www.rfc-editor.org/rfc/rfc7807>.