One of my favorite topics recently is REST, especially as it pertains to WCF. In fact, right now at work we are developing a product that uses RESTful services over a SQL database (with ActiveRecord to access the data) and an MVC 3 (with Razor) front end. Fun stuff. So I jumped on a few of the lectures about the technology to see what we could do to improve the process.
Turns out, one of the fundamental things we were doing wrong was how we handled the structure of the RESTful responses to the users: I'll go over this next part briefly. There are exceptions, but this is a good rule of thumb:
- When you do a select, either for an individual item or for a list of items, you want to do an http GET.
- When you do a create for a new item, you want to do an http POST.
- When you do an update for an existing item, you want to do an http PUT.
- When you do a delete (something I hate in general, by the way), you want to do an http DELETE.
Ok? Ok. For a brief aside: my first job involved two systems which drastically changed they way I think about deleting records. The first was the DMV system for a US territory. The second was the Title and Registration system for that same territory. I'll get into a fuller description of that in another post, but the short of it is in a system of that kind, you never want to lose a record of anything, ever. Police and courts will be wanting historical information, as in 'was this person, at any time, ever named Osama Bin Laden?'... maybe not that extreme, but you get the idea. So updates are king, and columns for start and end dates, and status changes (and histories on those changes, etc) become replacements for straight-up deletes. I try to carry that mentality with me: historical content is really handy, and unless you are changing state many many times a day, another row in a table isn't going to kill your system. Let the DBAs and Business Owners of the world handle how long to keep data, when to archive it and where, etc.
But back to the issue: RESTful responses for CRUD commands. If you've ever written a REST service and tested it out (say with Fiddler, which I highly recommend as a product for that), you'll notice your create commands come back as 200s. That's fine, but it's not a 'correct' response. What you should send back on a successful create is a 201, plus a link to the new Uri in the header. Luckily .Net 4.0 has this built in as a nice new feature to help you out:
- WebOperationContext.Current.SetStatusAsCreated(newUri)
This command (which is in System.ServiceModel.Web) automatically does both of these things. The one caveat is you will need to construct that new Uri, but I'm assuming you know the select structure already, since there would be little point building the Create without the Read in your CRUD already, just for testing purposes.
Another fun tidbit: WCF 4 comes with automatic content negotiation, which can be really handy when you want to get your responses in, say, json and not xml, because you are a l33t Android programmer and want to just take your objects and run with them. Most of your headers for http GETs when testing your handy new RESTful services will have a line in them like "accept: application/xml". What you can now do is change that to "accept: application/json" and it will format correctly, without any service-side changes. This is very useful for clients across multiple platforms, which is one of the inherent strengths of REST already: this just makes it even more versatile.
This article is a little informal, I'm still trying to find my 'voice' in this format. Hopefully in the future I'll find the time to structure these and include things like code samples, etc. I welcome any questions or comments, and thanks for reading!
References for this article:
Yes, Atlanta really is this bad
MSDN OutgoingResponse (For setting a 201)
PDF for the specific lecture this article discusses
REST in Practice (O'Reilly book)
No comments:
Post a Comment