The RESTful Post Office

REST is a hard thing to describe sometimes. There are clear definitions for the verbs but sometimes it's not always easy to pick which one you should use for a particular case, so let's boil it down a bit. REST is based around a resource and you modify it using requests. In the below examples, the resource is a package. There are different verbs you cause to modify the package resource. You can GET, POST, PUT, and DELETE them. Of course it makes no sense in either case to just have a pile of packages somewhere, just like you wouldn't reach your arm through the internet to get or change. The packages would be at a post office and the resources are on a server. Now that we have that sorted, let's begin.


You have a receipt and have to go pick up a package from the post office. The person at the counter looks in the package with the same number as what's on the receipt. They then check who you are to see if they can give the package to you. If everything checks out, they hand it over and you leave. Somehow, the package regenerates so you can come back and get as many copies of the package as you like so long as you have you have the receipt and the package is addressed to you.


This one's pretty simple. You take the package to the post office. The person at the counter looks it over to make sure it has the proper postage, everything's wrapped up correctly, it's not a banned item, and it's got a valid address. They slap a label on it, give you a receipt with the package number on it, and they put away to ship it.


Now you realize you'd shipped the wrong package. You run back to the post office with another package and the receipt from the old package. The nice folks there look over the new package, make sure it fits all the criteria from the old package, and then go find the old package. If it's gone, you're out of luck. Otherwise, they tear the label off the old package, stick it on the new package, and throw the old one away. Your receipt is still good.


You realize you shipped something you shouldn't have and never want to see that package again. You run back to the post office with the receipt and ask for it to be destroyed. They check in the back to see if it's still there. If it's already gone, then they tell you as much and walk away distraught. If it's there, they take it out back, burn it, and then they tell you they've destroyed it.


Once again, you messed up sending a package. This time you need to change something in the package. Most post offices will try to give you the package back and have you reship it once you're really sure, but these people are really nice, so they'll let it slide. Once again they look for the package. If it's still there, they make the changes you specify, make sure everything's still fine with it, and then leave it in the back to be shipped away. If something goes wrong, they'll tell you as much and you'll have to deal with it yourself, probably by replacing it with another package with the changes already made.


You're just walked into a post office not knowing what it is. Let's assume it's a foreign country and you can't even take a stab at the language. Someone at the counter speaks your language and tells you that this is a post office. They also treat you like you're 4 years old and explain what a post office is.

Hopefully this helps when trying to explain REST to others and trying to work out which verb to use when writing RESTful APIs. If not, it's a bit of fun.

Day 65 of #100DaysToOffload

Tags: Programming API REST