2. HTCPCP Protocol
The HTCPCP protocol is built on top of HTTP, with the addition of a few new methods, header fields and return codes. All HTCPCP servers should be referred to with the "coffee:" URI scheme (Section 4).
2.1. HTCPCP Added Methods
2.1.1. The BREW method, and the use of POST
Commands to control a coffee pot are sent from client to coffee server using either the BREW or POST method, and a message body with Content-Type set to "application/coffee-pot-command".
A coffee pot server MUST accept both the BREW and POST method equivalently. However, the use of POST for causing actions to happen is deprecated.
Coffee pots heat water using electronic mechanisms, so there is no fire. Thus, no firewalls are necessary, and firewall control policy is irrelevant. However, POST may be a trademark for coffee, and so the BREW method has been added. The BREW method may be used with other HTTP-based protocols (e.g., the Hyper Text Brewery Control Protocol).
2.1.2. GET method
In HTTP, the GET method is used to mean "retrieve whatever information (in the form of an entity) identified by the Request- URI." If the Request-URI refers to a data-producing process, it is the produced data which shall be returned as the entity in the response and not the source text of the process, unless that text happens to be the output of the process.
In HTCPCP, the resources associated with a coffee pot are physical, and not information resources. The "data" for most coffee URIs contain no caffeine.
2.1.3. PROPFIND method
If a cup of coffee is data, metadata about the brewed resource is discovered using the PROPFIND method [WEBDAV].
2.1.4. WHEN method
When coffee is poured, and milk is offered, it is necessary for the holder of the recipient of milk to say "when" at the time when sufficient milk has been introduced into the coffee. For this purpose, the "WHEN" method has been added to HTCPCP. Enough? Say WHEN.
2.2. Coffee Pot Header fields
HTCPCP recommends several HTTP header fields and defines some new ones.
2.2.1. Recommended header fields
2.2.1.1. The "safe" response header field.
[SAFE] defines a HTTP response header field, "Safe", which can be used to indicate that repeating a HTTP request is safe. The inclusion of a "Safe: Yes" header field allows a client to repeat a previous request if the result of the request might be repeated.
The actual safety of devices for brewing coffee varies widely, and may depend, in fact, on conditions in the client rather than just in the server. Thus, this protocol includes an extension to the "Safe" response header:
indication will allow user agents to handle retries of some safe requests, in particular safe POST requests, in a more user-friendly way.
2.2.2. New header fields
2.2.2.1. The Accept-Additions header field
In HTTP, the "Accept" request-header field is used to specify media types which are acceptable for the response. However, in HTCPCP, the response may result in additional actions on the part of the automated pot. For this reason, HTCPCP adds a new header field, "Accept-Additions":
2.2.3. Omitted Header Fields
No options were given for decaffeinated coffee. What's the point?
2.3. HTCPCP return codes
Normal HTTP return codes are used to indicate difficulties of the HTCPCP server. This section identifies special interpretations and new return codes.
2.3.1. 406 Not Acceptable
This return code is normally interpreted as "The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request. In HTCPCP, this response code MAY be returned if the operator of the coffee pot cannot comply with the Accept-Addition request. Unless the request was a HEAD request, the response SHOULD include an entity containing a list of available coffee additions.
In practice, most automated coffee pots cannot currently provide additions.
2.3.2. 418 I'm a teapot
Any attempt to brew coffee with a teapot should result in the error code "418 I'm a teapot". The resulting entity body MAY be short and stout.