REST – a quick summary

I’d read a lot of blogs talking about REST and it’s benefits but I hadn’t fully got it. Whilst on holiday I read RESTful Web Services, which I had seen recommended, in an effort to try and finally grok REST.

I thoroughly recommend this book, it helped me connect a lot of previously separate ideas into a coherent whole. What I hope to do here is give an overview of what I’ve learnt from the book to act as a reference to myself and maybe help other people in the process.

Definition

REST is short for Representational State Transfer. Distilled down, it’s basically about using the HTTP verbs, GET, POST, PUT, DELETE and HEAD, in order to act on resources, represented by individual URIs.

Resources are similar to what most of you will think of as domain entities. However, a relationship between two entities can be represented by a resource.

Underlying principle

The main idea behind REST is that you are working with the HTTP protocol. Other web service ideas like SOAP, referred to in the book as Big Web Services, mostly ignore the expressiveness of the HTTP protocol and use only GET and/or POST requests. This often works against the HTTP protocol, at best it ignores .

The requests and responses of the HTTP protocol consist of a head and a body. The analogy used in the book is one of an envelope, the head being the envelope and the body being the contents of the envelope. REST uses the URI, HTTP verbs, HTTP headers and HTTP response codes in order to communicate to the server what is wanted and to the client what happened.

This is in contrast to SOAP which generally uses the URI from the head and then sends another envelope in the body to communicate more information about the request to the server and the response to the client. This is effectively putting an envelope inside another envelope.

HTTP verbs and their meanings

The beauty of the verbs are that they are mostly self-explanatory, but I’ll explain all of them for completeness.

GET

This verb means give me the current representation for the given URI. You can use headers to modify the behaviour slightly. For example, the If-Modified-Since header can be used to say “only send me the representation for the URI if it has changed since the given date”. This can be used to minimize needless traffic and processing.

DELETE

This verb means delete the representation at the given URI. There’s not really anything complicated about it.

HEAD

This is equivalent to a GET request but only returns the HEAD of the response, omitting the BODY. This is used for getting the meta data about a resource, for example checking whether a resource exists at a given URI without retrieving the BODY as well.

POST and PUT

I’ve put these two together as they are the ones I previously had most difficulty differentiating between. Needless to say the book explained the difference perfectly.

PUT is used to place a resource to a specific URI (eg. /Product/1), this can be a resource that didn’t exist before (an insert) or replace the existing representation at that URI (an update). In contrast, POST is used to add a resource to the end of a list of resources (eg. /Product) when you don’t know the URI in advance (an insert). Once you know the URI of your new resource, you will use a PUT to update it.

REST and HTML forms

A problem I had was reuse of web service code with web sites, HTML only supports the verbs GET and POST. I was concerned about having to maintain two sets of code for acting on the same resources. This can be overcome by using a concept called overloaded post.

The idea behind it is really simple, you include the verb you want to use as a query string parameter and POST to that URI (eg. /Product/1?method=DELETE). Then using some simple server-side code you handle the request as the verb passed instead of as a POST.

Conclusion

I’ve covered the main concepts that helped me understand the big picture of REST. I really think it is the best way to write web services so that they can be easily consumed by other people. The emphasis of REST is on simplicity, utilising the power of the HTTP protocol rather than building a new protocol on top of it. This goes against the common practice up until this point, which to me is a breath of fresh air.

Finally, I strongly recommend you buy the book if you are interested in learning more about REST.

Nott Tuesday and the altnetbeers format

As I said previously I’ve volunteered to lead this month’s Nott Tuesday event, taking place this coming Tuesday, 14th July.

So, as promised, I’m going to give the outline of how the whole evening will work. Hopefully it will encourage more participation from the whole group in the discussion, improving the night for everyone.

Topic selection

So a little while after 18:30, once everyone has had the chance to say hellos and so forth, I’ll ask everyone to volunteer topics for discussion. I’ll provide a stack of index cards and pens and anyone who has something they’d like to talk about can write a question on a card and put it onto a table for others to see. Something as vague as “why agile?” or specific as “how do I leverage e-marketing to obtain new business?” is fine. Framing it as a question will probably work better, but if you can’t do that then a simple sentence will do. The idea is to give the group a starting point for a discussion.

Once we’ve had 5-10 minutes to write down our ideas we will whittle them down to the few most popular topics by voting on the ideas as a group. We’ll start off with the most popular topic and if the discussion is lively enough for long enough that might be all we discuss all night but if things start tailing off we’ll move on to the next most popular topic.

How does the discussion work?

There will be a “bench” where 3 people sit, they are the panel of which the group can ask questions. To begin with I’ll ask whichever person raised the topic to speak for 30 seconds or so just to explain a bit further what they want to get from the discussion. This person will also start off on the bench along with 2 volunteers. It is then thrown to the floor to ask questions of the bench. If you have a question, raise your hand and I’ll pick a person at a time to ask their question to stop it being a free-for-all. If you are part of the audience, you can only ask questions or come back on the answers given by the panel when applicable.

If it is a topic you are interested in and have something to say about it, you can go and sit in the “hot seat”, this signifies you want to be on the bench and answer questions. When someone is in the hot seat, someone from the bench is obliged to return to the audience, allowing the person in the hot seat to move onto the bench. This can manage itself by people not having more to say or wanting a break, but if not we’ll do it on a first-in-first-out basis.

A personal plea

Please be gentle with me, it’s the first time I’ve run something like this so bear with me a bit. I might need to cut you off if you’re in the middle of a heated discussion but the majority of the room looks bored, please bear in mind I’m trying to keep it interesting for the whole group. There’s nothing to stop your carrying on the discussion afterwards of course!

That’s all there is to it really. Hopefully, it will result in an enjoyable evening for everyone, having lively discussions about topics we’re all interested in.

See you at Bluu on Tuesday 14th July at 18:30!

Nott Tuesday – July 14th

So I went to Nott Tuesday for the first time last month and really enjoyed it. Adam Bird, the guy who started it up seemed keen to move towards group discussion rather than one or two people presenting to the group.

I’d been to a similar event before, altnetbeers, which is run by Sebastien Lambla in London. Altnetbeers had the sort of group discussion I felt Adam was looking for so I dropped him an email the next day explaining the format to see what he though.

Well I should have known better because, as has now been announced, Adam said he liked the sound of it and asked me if I wanted to lead the next meeting in the style of altnetbeers. I couldn’t well say no after telling him how great it was so here we are.

I’ll be cross posting an explanation of how it all works a bit nearer the time so that people will have an idea of what will be happening on the night.

Opening a Command Prompt for the solution in Visual Studio

Something I’ve found myself needing to do more recently is open a command prompt at the root directory of my solution. Often this is to run a rake task or something like that.

The way I used to do this was rather long winded, but now I’ve got it down to a single key combination and I’ll explain here how you can do the same.

Firstly, open up the external tools dialog in Visual Studio:

 

Then add a new tool:

This will give you a prompt to type the details of the new tool into:

Then fill in the details of the new tool. We want to point this at cmd.exe which is usually located in your System32 directory. You also want to set the initial directory to the solution directory:

I have then moved the tool up the list just because I like it being higher. The position of the tool in the list only makes a difference when setting up a keyboard shortcut as I will explain in a minute:

Once you’ve filled in all the details and moved the tool to the position you want it in just click Ok. You will now see that the tool you just created appears in the external tools section of the tools menu:

Now we can set up a keyboard shortcut for the new tool. Firstly, open the options dialog:

Then go to the keyboard section:

Then type in the command name “Tools.ExternalCommandX” where X is the number your tool appears in the list. Mine is second so I type “2”:

Then assign a key combination to this command. I chose Ctrl+Shift+Alt+C:

Then click ok and you will now be able to open a command prompt at the root of the current solution with your key combination.

This principle can be extended to call any program, you may have noticed I use it to call the default rake task for my solution.

Establishing Team Values

One of the biggest things I took from the Progressive .NET tutorials was the idea of establishing a set of values for your team.

This was raised in David Laribee’s session Towards A New Architect (watch out for the video of that coming out) where he asked whose team had a set of common values. In a room of 30 or so people, I think 3 or 4 raised their hand.

As soon as it was mentioned it made sense to me. A shared identity and core set of values can only benefit a team. To that end I’m going to run a similar session to the one I participated in in order to establish a set of values for my team.

I thought I might share the format I’m going to use so that others might do the same:

Set up a 1 hour session for discovering your team’s values

5 minutes explaining what we are doing and what we want to achieve

• bring common values to the fore
• give a common identity to the team
• create a catalyst for improvement

DIVERGE, CONVERGE, SYNTHESIZE

• 5 minutes writing words or short phrases down
• 5 minutes converging to write all the different phrases on the board by going round the group
• 2 minutes dot voting
• 1 minute selecting top 3-5 by votes

DIVERGE, CONVERGE, SYNTHESIZE

• 10 minutes to write a sentence explaining why each phrase is important (each person doesn't have to do each one)
• 10 minutes coming together, taking each word in turn and sharing sentences all written on the board
• 2 minutes tweaking and eliminating duplicates
• 2 minutes dot voting each group of sentences
• select the favourite sentence for each phrase

Your team now has a set of common values

Thank the team and tell them you are going to get them printed to put up on the wall. The important thing is that they are visible and prominent.

Important points

• the number of values should be low – the messages should be simple and strong
• the values should be visible to the whole team, all the time
• everyone should be empowered to act to strengthen the values

I’ll blog about what values my team at Open Projects have chosen next week.

Great replication troubleshooting article

I found this article on troubleshooting replication woes, unfortunately it requires you to sign up for SQL Server Central. However, if you have the “pleasure” of dealing with replication it gives a lot of good pointers on sorting out problems so it’s worth it.

Related posts:

• SQL Server 2005 replication errors table

When geek rockstars go wild

Ok, a silly one but I’ve got to share this. When walking to the hotel on Sunday before Progressive .NET I saw this in the middle of the pavement:

I’m guessing someone broke the build and this is what happened to their monitor.