RESTful Thoughts - Planned response status codes for the upcoming RESTful API

In the interest of honoring standards here is the response status code map for the upcoming Fellowship One RESTful API. Please comment / ask questions / make suggestions.

Many decisions made for this map came from RFC2616, Fielding's dissertation, and analysis of several dozen RESTful or REST "like" APIs currently on the programmable web.

200 - ok (GETs, PUTs, and DELETEs)

Entity body - The resource

Example - GET People/1

201 - Resource created (POST)

Response Header - Location will contain the canonical URI

Entity body - the new resource

Example - POST People

301 - Moved Permanently

Response Header - Location will contain the new permanent canonical URI

Entity body - will be empty

Example - GET People/1 has been merged and no longer exists the new URI is People/1

400 - Bad Request: There is an error on the client side.

Response Header - No modification

Entity body - Send back a message on why the request was bad

Example - Malformed XML fails to serialize eon the server

401 - Unauthorized

Response Header - WWW-Authenticate : OAUTH and the challenge or required parameter

Entity body - Optionally, a doc describing the failure

Example - missing OAUTH credentials

403 - Forbidden - Failed authorization

Response Header - No modification

Entity body - explanation of why authorization failed

Example - OAUTH credentials were good, however, the token used for the request was not valid or user associated with the token does not have rights to the resource

404 - Not Found: When a client requests a URI that does not map to a resource on the server

Response Header - No modification

Entity body - will be empty

Example - GET People/1 does not exist, optionally a 410 may be used (see below)

405 - Method not allowed

Response Header - Allow: GET, POST - list the HTTP methods the resource supports

Entity body - will be empty

Example - POST People/1/Status <- an attempt to create a status when only GET is available

409 - Conflict: Client tried to put the servers resource in an impossible or inconsistent state

Response Header - Allow: GET, POST - list the HTTP methods the resource supports

Entity body - will be empty

Example - POST People/1/Status <- an attempt to create a status when only GET is available

410 - Gone: server knew there used to be a resource but it's gone now

Response Header - No modification

Entity body - explanation of conflicts

Example - PUT People/1 modifying "Weblink" credentials for People/1 that are already used by People/2

415 - Unsupported Media Type

Response Header - Code detailed supported media types for the given resource

Entity body - will be empty

Example - Resource only supports XML and JSON, but the client sends application/atom+xm

500 - Internal Server Error

Response Header - No modification

Entity body - will be empty

Example - The server encountered an unexpected condition which prevented it from fulfilling the request.

This response status code map is subject to change, however, in the current build of the API these rules exist as defined above.

Web dev - Back to the basics

Some of the most important aspects of creating web based API, or any web based application is messaging and behavior - user experience. Back in 1999 when the HTTP 1.1 protocol was defined and the HTML 4.0.1 spec was released the web began to get more lively.

People stopped using World Wide Web and AOL interchangeably and we all jumped in our web dev boots, and rushed to inflate the bubble that would burst only a few years later.

courtesy of: Dana Summers, The Orlando Sentinel

Ironically, with web usage up, daily life being immersed in web jargon, popups, ads, and UI travesties, standards seemed to become less important.

All of those RFCs written by Fielding and gang seemed to melt away and get replaced by blinking text and Internet Explorer 5.0. I know I am generalizing; there we're a few outliers that challenged the norm and chose standards like the Netscape, but it seemed for the most part we used the web to showcase our madd skillz with using bloated back ground images and auto playing midi files for each "lucky" visitor <- I was, indeed, one of the worst violators of midi web attacks. The rule breaking was not limited to UI though, many services misused protocols and redefined established patterns in order to fit the web into antiquated business models.

Maybe that history muddied the standards / protocol waters; I mean shouldn't every web developer / architect know how HTTP works? What if we as developers simply relied on a tool or framework like visual studio and .NET to handle all of that crazy HTTP stuff for us? Would you hire a "Web developer" that did not know what the difference between a GET and a POST was?

I was blessed to have had an opportunity to go to MSDN Dev Con yesterday. I was sitting in a session ASP .NET 4.0 road map given by Ben Scheirman. He said something during his presentation that struck a web cord with me, I'll paraphrase:

With ASP .NET MVC, Microsoft looked at other MVC based frameworks and put together a solid tool to let developers do what they want to do and let the .net framework help and not get in the way.

For so long now, many .net developers have been using tools to write their HTML and CSS for them. We have ignored the basics. I chose ASP .NET MVC because of the flexibility of the pattern (not because of the Microsoft technology) and I truly enjoy the fact that standards and practices whet into the making of it (begin soapbox - I do not like how you can decorate your actions with HTTP verbs - would I ever do a post on a show? If so, wouldn't I be breaking the convention of the pattern? - end soapbox).

I find myself having to go back to things like RFC2616, Fielding's dissertation (when working on the RESTful API), and even the HTML spec daily. I find those tools far more valuable than an IDE or a managed framework.

Fearlessly tweak IIS

I find that I wreck my development machine often, either because I over-tweak or because I a messing with something that I have never messed with before.

IIS on Vista / Server 2008 is one of those things where messing with it outside of the configuration interface can really jack things up - almost to the point of having to reinstall IIS or even your OS.

I came across this a while back (I can't remember the source, so credit can go to the tech fairy) - before messing with IIS (even through the configuration panel) you should backup the configuration files IIS uses - here's how...

Let's go really low-tech and create a simple bat file to get the job done:

1. Create a new bat file and name it something like: backupiis.bat
2. Put the following code in it (changing the value of DestPath) -
   SET DestPath=e:\backups\

@For /F "tokens=2,3,4 delims=/ " %%A in ('Date /t') do @(
Set Month=%%A
Set Day=%%B
Set Year=%%C
)

copy C:\Windows\Microsoft.NET\Framework\v2.0.50727\CONFIG\machine.config %DestPath%machine.config_%Year%%Month%%Day%
copy C:\Windows\System32\inetsrv\config\applicationHost.config %DestPath%applicationHost.config_%Year%%Month%%Day%
3. Execute by double clicking on the bat file or setup a scheduled task

Now you can fearlessly go tweak IIS!

Final thoughts and upgrades on the Dell Mini 9

The Mini seems to be an overall win for my wife. She's really been enjoying it.

Her ups are that she can take it any where she goes, she can actually use it while holding the baby, she gets "oohs" and "ahhs" everywhere she goes - people find it hard to believe that she just pulled a full blown computer out of her purse, it's comfortable to her - she is not bothered by heat or weight when setting it in her lap, after the upgrades I made (more below) she says that the speed and multitask-ability is out of the park!

Her downs are sometimes when she gets into a typing grove she mistypes due to the slightly smaller keys and the screen resolution has taken her a little time to get used to (she is accustomed to 1024 x 768 and not the current max 1024 x 600).

Here's the story:
After it arrived on Dec. 23 I knew it would be pretty cool to transfer all of her docs, and settings from her old laptop (D600) to the Mini, wrap it up and stick it under the tree. So that night I whipped out her old box, the Mini, and a usb DVD drive and got to work.

Initially when the Mini booted I was somewhat impressed. After going through setting up the user, computer name, network, etc... the thing would boot up in around ~10seconds, and would finish loading apps, anti virus, etc.. in upwards of 30seconds - not too bad.

I installed Office 07, configured the local network shares (transferred docs and pst files from network shares), setup her email, and then started the windows updates. Prior to the updates I noticed that the transfer of many files (her entire my docs directory) over wireless to our NAS was significantly faster than even the m90 I use for work. I cracked it open and looked at the wireless card - nothing special just an 802.11g card. I never did any benchmarks, by my impression is that the file writes and reads over the network are fast (possibly the new Atom processor, or SSD and it was simply writing faster to the media - I don't know, and I really don't care).

I was disappointed with the number of windows updates I had to do. The installed configuration was Windows XP sp3 and Office 07 retail. I ended up having to download somewhere in the ball park of 70+ updates coming in at 600~700mb total! This wasn't a major problem for me since we have FIOS and the updates we're downloaded almost instantly but the reboots for the updates and shear number was disconcerting - I can't imagine the frustration of a Cable or DSL user. Dell and Microsoft need to work on this one, whether its an additional CD packaged with the product when the updates reach a certain number, or the image Dell uses is updated more frequently - not sure, I am just guessing there must be a better solution.

After all of the housekeeping was done I cleaned up the loose / temp files installed firefox, configured the box to hibernate on lid close, and wrapped it up.

She was excited when she opened it, her first words about it, "this thing looks sweet." After some usage she was feeling the pinch of her usage patterns pushing the limits of the netbook. It began to crumble over her 1gb archive of email and Windows was constantly having to adjust the pagefile size because of virtual memory usage.

I began questioning if I had made the right decision, maybe I should have gotten her a Dell Studio or a something else. I did a brief bit of research and discovered one of the major bottle necks of many of the netbooks is the write speed of the SSD and multitaskers should have as much memory as possible (side note, the tech specs on Dell's site says Up to 1gb - the current configuration I have is running and using 2gb).

Thanks to mydigitaldiscount and the jkkmobile blog all of my problems when away for $140. I bought the new RunCore PCI-e 32gb SSD and a 2gb stick of Transcend memory. With the help of the awesome configuration of the RunCore drive and the Acronis trial I had her drive cloned in 10 minutes.

I first bench marked the current drive that came with the mini - 16gb SSD by STEC. I was disappointed in both the reads and the writes with this drive. It's seems that Dell might have skimped on this, I am not sure why though - I personally feel that this is one of the more important areas of the unit. At least give me an option on the site to upgrade to a high performance SSD when I am buying the Mini (this btw is my only gripe about the Mini 9 - everything else has far exceeded my expectations).

Dell really out did themselves with the hardware accessibility of this unit. You can flip the unit over and pop off the back panel (roughly 3in x 4in opening). There you have access to WLAN, Wireless, Memory, and SSD - perfect!

I dropped in the new SSD and memory closed it up - all in about 5 minutes. I booted up the Mini and voila - an exact copy of the drive minutes before, running perfectly - all done in under 20 minutes.

The benchmarks on the new RunCore SSD we're impressive and crushed the SSD from STEC that came with the Mini.

(Standard 16gb SSD that ships with the Mini)

(RunCore 32gb SSD purchased for $119.00)

Final thoughts:
Initially I was concerned about getting a netbook but, during my research when considering what to get her based on her needs the Mini 9 kept coming up. The configuration seemed solid and the size is a perfect fit for her. She delights in simplistic things - "don't give me something I don't need, I want to get stuff done, plain and simple. If it gets in my way of getting things done, I get rid of it..."

If you are an "on-the-go" user, a digital nomad of sorts and you live in email, the web, and in spreadsheets than this is the box for you. She has zero problems with photo and movie editing as well (especially after the upgrades). It is rare that a tool shows up in the tech smelting pot that actually makes the user who moves through insane situations and crazy environments more effective - I believe this is one of those tools. It's an elegant, fast, no frills solution to the person with the high demand life where every second counts.

Well done Dell, though your flagship laptop line is the Precision series - I really do think this one will change / impact more lives. My wife so far has been relishing in the benefits of using this computer in all areas of our lives. Get the SDD right, or at least provide an option and you'll own the netbook market.

Go to my Flickr photostream to see all of the photos from the upgrade.

My wife, the hypermedia Mom and her new Dell Mini 9

Over the holidays I bit the tech bullet and bought my wife a new netbook. Her current laptop was crumbling under the musings of a 4 year old and his wicked wild key strokes - and it was simply time to replace it.

Let me to set the stage:
We have 3 very energized boys (ages: 4yr, 2yr, 9mo). My wife is a "stay at home mom", an E.R. nurse, and a MOPS ministry leader / coordinator at our church. She is constantly on the move. During the day she and the kiddos will hit the local zoos, libraries, museums, etc. At night sometimes after everyone goes to bed she and I chat while I sling code and she works on the ministry.

All of those activities require that she be knee deep in hypermedia, or something digital. She is either teaching the kiddos about the internet, taking pictures with them and uploading them to our media server, getting her excel fix for MOPS, she does budgets, rosters, sends and receives 100's of email every day, prints media for ministry and the family, edits photos, etc...

She is a digital nomad - who roams DFW providing salve to scratched knees, defending against lost drinks and misplaced toys, crusading for ministry needs, and smiting poopie diapers; all while somehow staying connected and productive at home, church, and work. My wife is the Joan of Arc of the digital age - she is the strongest most connected woman I have ever known.

Her requirements for a computer were simple - It needed to be fast, small / highly portable, easy to use, have decent battery life, and durable. I looked at a few options but the best bang for the buck was the Dell Inspiron Mini 9.

Here's the configuration that I ended up with:

• Inspiron 910 Intel Atom processor N270, 1.6GHz, 533Mhz512K L2 Cache
• CHERRY RED Color with Gloss Finish
• 1GB,DDR2,533MHZ,1 DIMM
• 16GB Solid State Drive (mini-card Module/PATA)
• Genuine Windows XP Home Edition (would've preferred ubuntu)
• Wireless 802.11g Mini Card
• Integrated 1.3M Pixel Webcam
• 32WHr 4-cell Battery
• Bluetooth 2.1 module via USB I/F

After a bit of coupon searching I ended up with a solid price and a sweet timbuk2 convert bag. I will be grilling her over the next few weeks about it and post a review / update. So far none of our little minions have thwarted the mini's durable exterior and she is able to type wicked fast on the mini's keyboard with one hand while holding the baby.

I have already purchased 2 goodies that I am totally looking forward to installing in her mini soon:

• RunCore Pro 32GB Mini PCIe SSD(supposed to be 3~4 times faster on writes that the default from Dell)
• Transcend 2gb module (she is a heavy muli-tasker and 1gb just won't cut it)

I'll bench a before and after for those who are interested.