Carrot Versus Orange

There has been a brewing discussion on the wiki on how the AtomAPI needs to be structured. While the discussion is long and some of the issues murky, the question is quite simple and is boiled down into one poll.

The poll, which was on RestEchoApiDiscuss, but through the wonder of wiki has now migrated to CarrotVsOrangeDiscuss. The poll is restricted to just looking at the simple case of editing an Atom Entry, and the question is "What should the relationship between URIs and HTTP verbs be?"

1. One URI for create, edit and delete
2. Each Entry has it's own URI that accepts GET, PUT, and DELETE

One of the misconceptions hinted at in the discussion on the wiki, but never flatly stated is that if you choose #2 you can't run everything through a single CGI script, which will make the system difficult to implement or hard to maintain. This isn't true and I have implemented both interfaces in Python in a side-by-side comparison to demonstrate that they can both be done in a single CGI.

The first script implements option #1:

#!/usr/bin/python 
  
import cgitb; cgitb.enable() 
import os, cgi, urlparse, sys 
import myLowLevelBloggingAPI 
import xmltramp 
  
  
method = os.environ['REQUEST_METHOD'] 
id = None 
  
if method == 'POST': 
   content = sys.stdin.read() 
   d = xmltramp.parse(content) 
   if d._name == 'delete': 
      myLowLevelBloggingAPI.delete(d('id')) 
   try: 
      id = d.entry.id 
   except: 
      pass 
   if id == None: 
      id = myLowLevelBloggingAPI.create(sys.stdin.read()) 
      print "Status: 201 Created" 
      print "Location: " + urlparse.urlunparse\
         (('http', os.environ['SERVER_NAME'],\
         os.environ['REQUEST_URI'] + '/%d', '', '', ''))\
          + "\n" % (id, ) 
   else: 
      myLowLevelBloggingAPI.update(id, content) 
      print "Status: 205 Reset Content\n" 
elif method == 'GET': 
   id = os.environ.get('PATH_INFO', '') 
   print "Status: 200 Ok\n" 
   print myLowLevelBloggingAPI.get(id) 

The second script implements option #2:

#!/usr/bin/python 
  
import cgitb; cgitb.enable() 
import os, urlparse, sys 
import myLowLevelBloggingAPI 
  
method = os.environ['REQUEST_METHOD'] 
id = os.environ.get('PATH_INFO', '') 
  
if method == 'POST': 
   id = myLowLevelBloggingAPI.create(sys.stdin.read()) 
   print "Status: 201 Created" 
   print "Location: " + urlparse.urlunparse\
      (('http', os.environ['SERVER_NAME'],\
      os.environ['REQUEST_URI'] + '/%d', '', '', ''))\
      + "\n" % (id, ) 
elif method == 'GET': 
   print "Status: 200 Ok\n" 
   print myLowLevelBloggingAPI.get(id) 
elif method == 'PUT': 
   myLowLevelBloggingAPI.update(id, sys.stdin.read()) 
   print "Status: 205 Reset Content\n" 
elif method == 'DELETE': 
   myLowLevelBloggingAPI.delete(id) 
   print "Status: 200 Ok\n" 

There are several additional things to note from these example implementations:

1. If either of these cgi scripts were installed as atom.cgi on example.org then doing a GET on http://example.org/atom.cgi/1 would get the Entry with an 'id' of 1.
2. Note that in the second example all the dispatching is done via the HTTP verbs, no parsing of the content is necessary.
3. For both examples there is a single CGI script that processes the requests.
4. Option #2 is a far simpler script that option #1.