MadZak

If you are a web developer you will obviously know that we have some fancy http verbs hanging around in the specification like GET or POST. PUT is a verb that although seldom used, provides a very distinct way of manipulating the URI. Getting down to the semantics, here's the definition of PUT:

The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI.

So basically a PUT allows us to create or update a specific URI. PUT isn't really utilized in the standard browser web process for some reason, but it has had a resurgence since the Restful movement began. Here is where the nerd fight begins (i'm guilty of having it as well).

POST has been the defacto method for creating since the beginning of time. Maybe not that far back, but as far as this developer remembers on the web. So naturally people kind of default to this method as for creating things. This is great and it should be this way because reading the definition, this is the verb for creating:

The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line. POST is designed to allow a uniform method to cover the following functions:

It then goes on to describe common functions like posting article to group, appending to a database, sending data for processing, and the final one is this "Annotation of existing resources;" And this is what I believe to be the one vague bullet point that bring up the fight of POST vs PUT. 

So how do we look at it? Technically it's adding to whatever URI you've given it. Some take that to mean it functions exactly like a PUT. I believe it doesn't. Simplifying the verb a bit, we can understand that POST is append and PUT is replace. The key point here is the PUT action is replacing the entire contents of the URI. On the other hand, the POST action is adding to the contents that are already available at the URI.

Lets dive into a simple example of a restful api around file structures:

== POST ==

GET URI: /api/folder/
Folder
  -> dir1
  -> dir2
  -> text.xt 

POST madzak.txt=text to URI: /api/folder/
GET URI: /api/folder/
Folder
  -> dir1
  -> dir2
  -> text.txt
  -> madzak.txt 

POST madzak.txt=text2 to URI: /api/folder/
GET URI: /api/folder/
Folder
  -> dir1
  -> dir2
  -> text.txt
  -> madzak.txt (text)
  -> madzak.txt (text2)

== PUT  ==

GET URI: /api/folder/
Folder
  -> dir1
  -> dir2
  -> text.xt 

PUT madzak.txt=text to URI: /api/folder/
GET URI: /api/folder/
Folder
  -> madzak.txt (text)

PUT madzak.txt=text2 to URI: /api/folder/madzak.txt
GET URI: /api/folder/
Folder
  -> madzak.txt (text2)

This is how I (and i believe other purists) interrupt the implementations of the spec to behave. Notice how in the PUT if I used the same URI as the POST I removed that whole directory structure. This is because it's a replace not an append. Should you want to add the madzak.txt file to the existing structure you'd naturally use a POST because it appends. You could however use a PUT by changing the URI to be /api/folder/madzak.txt, which you see I did in the update PUT request. This says Create or Replace what's at this current URI. Given that madzak.txt doesn't exist, the implementation could create madzak.txt within that folder.

I'll leave you with my final comments on this topic. Just because the industry follow a certain way, doesn't make it correct. If you want to claim you are truly a restful interface, the spec says you should behave this way. If you don't want to follow the spec then make it abundantly clear in the documentation you using different behavior. Although i find it a bit foolish to write more documentation when you could just follow spec and point to what is already written.

HTTP Spec: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

I think you could call what I did for the last three days a binge of sorts. A colleague and I have started to use campfire in an effort to log communications and keep a steady flow of information going between our now hectic (love you family) and un-sync'd work efforts. Given my strong love for desktop clients, or real apps as I like to call them, I naturally went out searching for a linux client.

My searching didn't take long and I landed what was and will be my upcoming addiction called, Snakefire! Every time I see that name i think of the saturday night live skit about riding the snake with will farrel! Anyway this fancy little app was written by a cool gent named Mariano (http://marianoiglesias.com.ar/). He did some very nice work, although it's in QT at least it's python! I'll just wait until the GTK rewrite :)

So after using the application for a little while, I noticed a few things weren't working and also some missing features, or at least i thought they might be features. Given the code base in good shape, it being on Github, and it being python i thought what the hell... let's do it rather than ask for it. After about an hour, which was mostly spent understanding QT and how it works, i whipped up the ability to hide the join and part messages (ANNOYING!). I worked up my pull request and shipped it off to the master repo. As soon as that was done, I began checking my pull request every 15 minutes.

I was like a little boy on christmas day who sent his letter off to santa and kept waking up christmas eve to see if his request was delivered. Needless to say we were on different time schedules and my 15 minute check up went without a response for awhile but i pressed on, checking immediately as I woke up Monday morning.

It was accepted! HOLY SHIT! I got something into an app and I loved it! It was such a rush of accomplishment i could barely contain my excitement. It was from that moment that I became addicted. This same process occurred later that evening when I fixed the alerting system for gnome/xcfe setups and added inactive notification options. Another pull request was submitted and Github was forced to reset every 15 minutes in anticipation of acceptance.

Again I went to bed and woke up to find it accepted again! Man two of em were taken, i was totally making this product better. Obviously i couldn't stop, and i couldn't just add small features in... i wanted something challenging. So what did i begin working on that Tueday? I re-worked the display panel to be a web view so that images would be inline, hooked up drag and drop image uploading and even auto scrolling. I also paved the way to allow us to style up the conversation window to make it purtty. Like I said, Hooked!

So am I done? Hell no, this is great and Mariano is a great remote development work buddy so we aren't going to stop now. We have a lot in store for this little app and I couldn't be any happier to be apart of it. Keep and eye on it, test it, or add some sweet features to it cause it really feels excellent to give back. https://github.com/mariano/snakefire