Lets talk about REST.
For my new project, I’m going with REST architecture. I’m not about to start a topic about why REST is better than <insert another architecture/technology here>, this is the way it’ll be because I think it’d be awesome to get a nice solid RESTful system out. REST is basically what your web browser does to view internet pages. It asks the server for some data (usually HTML document) and the server then sends it back to the browser. It can also do a few other things, like POSTing some data to the server (think of a forum, or facebook status updates). These type of things have been working well for browsers for a very long time, and only ‘recently’ have we begun to exploit this solid system for something a little bit better.
So today’s world has many devices and operating systems all needing to access data on the internet. For quiet some time there have been some issues over how we do that exactly. Some suggest SOAP, others will suggest more crazy ideas such as socket connections, but regardless there is one thing devices are doing more and more: Browse the internet. But the problem is that not everyone agrees how it should be done. Worse still, not every implements the same architecture the same way either.
And that’s where this blog entry is going to come in, this will be “my” way of doing the REST, stealing from a few sources and experiencing a few teething issues a while back, I’ve put some thought to the REST structure of things.
What is REST?
REST basically is the movement of data between server and “yourself” of which you can do 4 operations with the information being passed: PUT, POST, GET, DELETE. Now there are discussions and strict definitions that I barely understand over what exactly these 4 operations do exactly but they are comparable to CRUD and are often explained in such a way that:
PUT is equivalent to CREATE – any information you send with the PUT operation will magically store your data
POST is equivalent to UPDATE – you need to have some information that the system already has stored and with the POST operation, you can change that stored data
GET is equivalent to READ – basically it’s the way to get data out of the system (which you can then change and POST back)
DELETE is equivalent to DELETE – remove the data from the system.
One special note is that it’s considered correct to CREATE if the POST command is called for a non-existent resource. This raises questions to why you’d need PUT in the first place and this is where you start to get into the more strict technical aspects of PUT and POST. There is even some confusion that PUT is UPDATE and POST is CREATE and quite honestly; it’s all just too much confusion. Following RESTeasy and some of the Amazon stuff I’m sticking with PUT = CREATE, POST = UPDATE. I will not be supporting POST = CREATE.
The data structure I’ll be using is JSON for sure. XML (and by extension HTML) has served well, but JSON is smaller and thus better for everyone. Personally, I’d love it if everything moved away from XML, but that’s a blog for another day.
Different types of implementation
There are so many ways to do this rest thing, lets start with reading from the resource. So to do this rest thing, you need a URL (keep in mind, I’m using URL loosely in this blog all over, and could be changed with URI where suitable). URLs are tough to think about, and are critical to having some good thinking about how to do things. It becomes very easy to create bad implementations if you get your URLs wrong. Here is an example of different ways to GET the same data from a resource:
Now all of these are fine (except maybe the company one…) but you need to consider a 3rd party developer when making these. It should be easy to use and more importantly, consistent. You can guess from the above that I’m trying to get the data of persons whose id in the storage is 1. In the above there 2 ways I’m doing this. Using a query parameter (persons?id=1) or using a path parameter (person/1). Personally, I like the query parametes the most, and sometimes the path parameter really doesn’t make sense (what does the /1 mean? Is it the id, or the person’s name, or storage key?) but there are some times it does make sense. Go check out Amazons Queue service. It uses URL like this: https://sqs.us-east-1.amazonaws.com/12345/queueName. I believe the 12345 is the user account while the queueName is id of that queue. You then have operations on that queue, and for example to get a message off the queue (this is not how Amazon does it) you’d use something like this: https://sqs.us-east-1.amazonaws.com/12345/queueName?messageId=1 instead of the mess like this https://sqs.us-east-1.amazonaws.com?queueId=queueName&userId=12345&messageId=1.
So there has to be some thought into naming these URLs, which I’m still busy doing, add in the complexity of lists, and sub categories and you need a pretty consistent game plan. I’ll post more on that later.
For now, if you are interested in some basic REST, check out http://www.mkyong.com/tutorials/jax-rs-tutorials/ or if you want to see some hardcore stuff on the topic of REST, check out apigee and how they handle some of the REST stuff (find them on youtube as well)