Carrot vs. Orange
CarrotVsOrange discusses the benefits, drawbacks, and arguments for or against AtomApi approaches "HTTP using GET/POST to a single URI" (Carrot) vs. "HTTP using the REST Architectural Style" (Orange or simply REST).
-
PutDeleteFaq -- Frequently asked questions about PUT/DELETE support and usage.
-
PutDeleteSupport -- list of implementations and their level of support for PUT/DELETE. Virtually all servers support PUT/DELETE, most client libraries support PUT/DELETE fully, some client libraries require workarounds or use of a different library.
Poll
Place your name by the option you like best. [OpenPoll]
-
One URI for create, edit and delete (8)
-
Each Entry has its own URI that accepts GET, PUT, and DELETE (9)
-
KenMacLeod, MarkBaker, MortenFrederiksen, NickChalko, AsbjornUlsberg, JamesAylett, MikeDavies, HenriSivonen, BillDehora
-
Each resource you want to operate on accepts GET, PUT, DELETE, and POST. Each element within the atom model that you may want to operate on directly gets its own url.
Note: There is a third option where each resource has its own URI, and GET and POST are directed to the resource URI.
Note: Another option is to have one URI per entry, that accepts GET/POST/PUT/DELETE (REST) and that ALSO accepts a POST with the Content-Type for URL encoded HTML form data. In this way a web browser can use an HTML form to POST commands to the atom service and a REST client can use the direct manipulation REST operations (POST/PUT/DELETE) [BryanThompson].
[HansGerwitz] I want to vote for per-Entry URLs (yes, I meant that L) but with all operations possible via only GET and POST. Does that make me a Squash? [AndrewCates] is anyone aboe to explain WHY carrot is called carrot and orange called orange?
Example code demonstrating this poll is in CarrotVsOrangeExample. See also RestEchoApiDiscuss, CarrotVsOrangeDiscuss.
-
Tim Bray's proposal for an HTTP and XML only protocol using HTTP's GET and POST methods.
Ken MacLeod's proposal for an HTTP and XML, and any other content type, protocol using HTTP's GET, PUT, POST, and DELETE methods.
Benjamin Carlyle's proposal for an HTTP and XML, and any other content type, protocol using HTTP's GET, PUT, POST, and DELETE methods.
Initial clarification points
-
PUTting to one URI of a multiple-URI represented resource is allowable. RFC2616 section 9.6: "A single resource MAY be identified by many different URIs ... a PUT request on a general URI may result in several other URIs being defined by the origin server."
-
RFC2616: "The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. ... the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource."
-
The ApacheWeek Article about using PUT with Apache involves a specific requirement to push all PUT requests to one CGI script. This project has no such requirement.
Apache handling of PUT requests
There are at least five ways for Apache to be configured whereby one CGI script can handle requests, regardless of methods directed to a specific range of URIs:
-
Specify in <Directory> that all PUTs go to a specific PUTScript
-
Identify a CGI script for a directory (in which case all HTTP methods are passed to the CGI program)
-
Use mod_rewrite or mod_alias to a CGI-script (in which case all HTTP methods are passed to the CGI-program)
-
Put the publishing system in cgi-bin or other place where it can run as a cgi (in which case all HTTP methods are passed to the CGI program).
-
Use modules that front Java, Python, Perl or other server-based systems (in which case all HTTP methods are passed to the module).
Benefits and Arguments
GET and POST HTTP methods
Benefits
-
People will find it easier to handle. Dispatching all POST requests to a central handler is easier than setting up handlers to catch DELETE and PUT operations to a wide number of URIs. This gives the service a cleaner editiorial transaction route through a publication gateway resource.
-
As with CGI-derived frameworks, GET and POST requests can be handled by one CGI at one location without any configuration changes.
-
POST for changing an entry is allowable, since the client is supplying additional information, the server decides what to do with it (e.g. merging HTML content, marking modifications with ins and del tags). PingBack and comments would alter the state of the resource.
-
[AnswerMe] Is the HTML content the actual model, or should the data be the model and HTML one representation of that data?
-
RFC2616 (HTTP 1.1) does provide reasons for using POST on an entry (instead of a central resource), also a reasonable reading suggests that using POST as a PUT equivalent is allowable.
-
From a REST perspecitve, it would be incorrect to use POST to tunnel the equivalent of DELETE and PUT. Using REST requires using HTTP methods because not to do so reduces visibility.
Drawbacks
-
Typically not used in the REST architectural style.
-
POST has to handle a mix of different data requests: - creating, updating and deleting entries
-
This mix makes security impossible to handle at the web server and operating system level (e.g. using the Limit directives to allow users to add entries but not delete them).
-
The security must instead be managed in the script POST handler itself.
GET, POST, PUT and DELETE HTTP methods
Benefits
-
Security can be implemented on a method level basis, because the distinction between creating, editing and deleting is clear at the webserver level.
-
There is no need for custom handling code, since handling is defined by the HTTP method used.
-
The core Apache httpd supports PUT and DELETE. The default on-disk handlers reject anything other than GET and POST. It is the responsibility of the CGI script to determine what methods it should respond to.
-
HTTP verbs are analogous to databases: GET = select, PUT = update or insert, POST = update or insert, DELETE = delete
Drawbacks
-
The script has to support a much larger URI-space, since each resource has different URIs (so some form of CGI request dispatching is required - see "Apache handling of PUT" above). Because of this larger URI space that needs to be covered, the script is harder to write.
-
Not sure if I understand this argument. This sample implementation handles GET/POST/PUT/DELETE with a single CGI script on a default Apache install with no .htaccess tricks.
-
Apache web servers (maybe not limited to Apache) with FrontPage Extensions create .htaccess files denying PUT/DELETE.
-
IIS (and the filesystem) needs to be configured by an administrator.
-
A hosting provider may only provide one of the systems below that don't support PUT/DELETE and won't upgrade.
-
One fallback technique is proposed in DifferentlyAbledClients
-
Similar argument: a hosting provider may not provide support for a publishing system at all; what is a user expected to do in that situation?
Server-Side Platform support of PUT and DELETE
See PutDeleteSupport.
Client-Side Platform support of PUT and DELETE
See PutDeleteSupport.
Clients or Servers not able to use POST ''or'' PUT/DELETE for Atom API
See PutDeleteSupport.
Solutions for the Impass between Single API and PUT/DELETE camps
[AsbjornUlsberg] Maybe we should start working on a proxy (-API) that transforms a regular GET/POST request into GET/POST/PUT/DELETE? With such proxies, a PUT-disabled client can post to it with a specified XML format, and the XML is then parsed by the proxy and PUTted to the target server. It should, if we define something like this, be stressed that this API MUST NOT be used for directly POSTs, it should always be routed through a proxy. Hence, we can say that receiving aggregators SHOULD NOT support this API at all.
[RussellBeattie] We need to simply define both specs as "authorized" and establish a simple method for determining which format is used. A simple GET that returns the API type will be sufficient, and the client can cache that from that point on. I say let the developers vote with their code.
[MikeDavies] An intermediate proxy is a good idea with a caveat or two - it leads to the "two APIs problem", and if this proxy API looks like TimBray's original conception, then it would put doubt on the feasibility of a REST framework. If the proxy API is an interim solution "until user-agents support..." then it is the way to go. What we must be sure of is that the number of devices/frameworks requiring the use of this Atom Proxy reduces over time, in favour of full REST support. (And +1 for Russell's "let the developers vote with their code" - if its worth supporting, its worth writing code for it.)
[AsbjornUlsberg] I only want the proxy as a temporary solution until the different frameworks (and developers) supports and understands all HTTP 1.1 verbs. Then, they can be discarded, and the GET/POST/PUT/DELETE can be done directly to the source. Also, I don't want the proxy API to be equivalent to the aggregator API. They are not interchangable, and the proxy API should only be used when the aggregator API can't be supported directly. The proxy API is a fast and temporary soltions for people who don't have the possibility to use the aggregator API directly, and SHOULD be superfluous in a couple of years.