How I Explained REST to My Wife
Wife: Who is Roy Fielding
?
Ryan: Some guy. He's smart.
Wife: Oh? What did he do?
Ryan: He helped write the first web servers and then did a ton of research explaining why the web works the way it does. His name is on the specification for the protocol that is used to get pages from servers to your browser.
Wife: How does it work?
Ryan: The web?
Wife: Yeah.
Ryan: Hmm. Well, it's all pretty amazing really. And the funny thing is that it's all very undervalued. The protocol I was talking about, HTTP, it's capable of all sorts of neat stuff that people ignore for some reason.
Wife: You mean http
like the beginning of what I type into the browser?
Ryan: Yeah. That first part tells the browser what protocol to use. That stuff you type in there is one of the most important breakthroughs in the history of computing.
Wife: Why?
Ryan: Because it is capable of describing the location of something anywhere in the world from anywhere in the world. It's the foundation of the web. You can think of it like GPS coordinates for knowledge and information.
Wife: For web pages?
Ryan: For anything really. That guy, Roy Fielding, he talks a lot about what those things point to in that research I was talking about. The web is built on an architectural style called REST
. REST provides a definition of a resource
, which is what those things point to.
Wife: A web page is a resource?
Ryan: Kind of. A web page is a representation
of a resource. Resources are just concepts. URLs--those things that you type into the browser...
Wife: I know what a URL is..
Ryan: Oh, right. Those tell the browser that there's a concept somewhere. A browser can then go ask for a specific representation of the concept. Specifically, the browser asks for the web page representation of the concept.
Wife: What other kinds of representations are there?
Ryan: Actually, representations is one of these things that doesn't get used a lot. In most cases, a resource has only a single representation. But we're hoping that representations will be used more in the future because there's a bunch of new formats popping up all over the place.
Wife: Like what?
Ryan: Hmm. Well, there's this concept that people are calling Web Services
. It means a lot of different things to a lot of different people but the basic concept is that machines could use the web just like people do.
Wife: Is this another robot thing?
Ryan: No, not really. I don't mean that machines will be sitting down at the desk and browsing the web. But computers can use those same protocols to send messages back and forth to each other. We've been doing that for a long time but none of the techniques we use today work well when you need to be able to talk to all of the machines in the entire world.
Wife: Why not?
Ryan: Because they weren't designed to be used like that. When Fielding and his buddies started building the web, being able to talk to any machine anywhere in the world was a primary concern. Most of the techniques we use at work to get computers to talk to each other didn't have those requirements. You just needed to talk to a small group of machines.
Wife: And now you need to talk to all the machines?
Ryan: Yes - and more. We need to be able to talk to all machines about all the stuff that's on all the other machines. So we need some way of having one machine tell another machine about a resource that might be on yet another machine.
Wife: What?
Ryan: Let's say you're talking to your sister and she wants to borrow the sweeper or something. But you don't have it - your Mom has it. So you tell your sister to get it from your Mom instead. This happens all the time in real life and it happens all the time when machines start talking too.
Wife: So how do the machines tell each other where things are?
Ryan: The URL, of course. If everything that machines need to talk about has a corresponding URL, you've created the machine equivalent of a noun. That you and I and the rest of the world have agreed on talking about nouns in a certain way is pretty important, eh?
Wife: Yeah.
Ryan: Machines don't have a universal noun - that's why they suck. Every programming language, database, or other kind of system has a different way of talking about nouns. That's why the URL is so important. It let's all of these systems tell each other about each other's nouns.
Wife: But when I'm looking at a web page, I don't think of it like that.
Ryan: Nobody does. Except Fielding and handful of other people. That's why machines still suck.
Wife: What about verbs and pronouns and adjectives?
Ryan: Funny you asked because that's another big aspect of REST. Well, verbs are anyway.
Wife: I was just joking.
Ryan: It was a funny joke but it's actually not a joke at all. Verbs are important. There's a powerful concept in programming and CS theory called polymorphism
. That's a geeky way of saying that different nouns can have the same verb applied to them.
Wife: I don't get it.
Ryan: Well.. Look at the coffee table. What are the nouns? Cup, tray, newspaper, remote. Now, what are some things you can do to all of these things?
Wife: I don't get it...
Ryan: You can get them, right? You can pick them up. You can knock them over. You can burn them. You can apply those same exact verbs to any of the objects sitting there.
Wife: Okay... so?
Ryan: Well, that's important. What if instead of me being able to say to you, "get the cup," and "get the newspaper," and "get the remote"; what if instead we needed to come up with different verbs for each of the nouns? I couldn't use the word "get" universally, but instead had to think up a new word for each verb/noun combination.
Wife: Wow! That's weird.
Ryan: Yes, it is. Our brains are somehow smart enough to know that the same verbs can be applied to many different nouns. Some verbs are more specific than others and apply only to a small set of nouns. For instance, I can't drive a cup and I can't drink a car. But some verbs are almost universal like GET, PUT, and DELETE.
Wife: You can't DELETE a cup.
Ryan: Well, okay, but you can throw it away. That was another joke, right?
Wife: Yeah.
Ryan: So anyway, HTTP--this protocol Fielding and his friends created--is all about applying verbs to nouns. For instance, when you go to a web page, the browser does an HTTP GET on the URL you type in and back comes a web page.
Web pages usually have images, right? Those are separate resources. The web page just specifies the URLs to the images and the browser goes and does more HTTP GETs on them until all the resources are obtained and the web page is displayed. But the important thing here is that very different kinds of nouns can be treated the same. Whether the noun is an image, text, video, an mp3, a slideshow, whatever. I can GET all of those things the same way given a URL.
Wife: Sounds like GET is a pretty important verb.
Ryan: It is. Especially when you're using a web browser because browsers pretty much just GET stuff. They don't do a lot of other types of interaction with resources. This is a problem because it has led many people to assume that HTTP is just for GETing. But HTTP is actually a general purpose protocol for applying verbs to nouns.
Wife: Cool. But I still don't see how this changes anything. What kinds of nouns and verbs do you want?
Ryan: Well the nouns are there but not in the right format.
Think about when you're browsing around amazon.com looking for things to buy me for Christmas. Imagine each of the products as being nouns. Now, if they were available in a representation that a machine could understand, you could do a lot of neat things.
Wife: Why can't a machine understand a normal web page?
Ryan: Because web pages are designed to be understood by people. A machine doesn't care about layout and styling. Machines basically just need the data. Ideally, every URL would have a human readable and a machine readable representation. When a machine GETs the resource, it will ask for the machine readable one. When a browser GETs a resource for a human, it will ask for the human readable one.
Wife: So people would have to make machine formats for all their pages?
Ryan: If it were valuable.
Look, we've been talking about this with a lot of abstraction. How about we take a real example. You're a teacher - at school I bet you have a big computer system, or three or four computer systems more likely, that let you manage students: what classes they're in, what grades they're getting, emergency contacts, information about the books you teach out of, etc. If the systems are web-based, then there's probably a URL for each of the nouns involved here: student, teacher, class, book, room, etc. Right now, getting the URL through the browser gives you a web page. If there were a machine readable representation for each URL, then it would be trivial to latch new tools onto the system because all of that information would be consumable in a standard way. It would also make it quite a bit easier for each of the systems to talk to each other. Or, you could build a state or country-wide system that was able to talk to each of the individual school systems to collect testing scores. The possibilities are endless.
Each of the systems would get information from each other using a simple HTTP
GET. If one system needs to add something to another system, it would use an
HTTP POST. If a system wants to update something in another system, it uses
an HTTP PUT. The only thing left to figure out is what the data should look
like.
Wife: So this is what you and all the computer people are working on now? Deciding what the data should look like?
Ryan: Sadly, no. Instead, the large majority are busy writing layers of complex specifications for doing this stuff in a different way that isn't nearly as useful or eloquent. Nouns aren't universal and verbs aren't polymorphic. We're throwing out decades of real field usage and proven technique and starting over with something that looks a lot like other systems that have failed in the past. We're using HTTP but only because it helps us talk to our network and security people less. We're trading simplicity for flashy tools and wizards.
Wife: Why?
Ryan: I have no idea.
Wife: Why don't you say something?
Ryan: Maybe I will.
UPDATE: YAMAMOTO Yohei has provided a Japanese translation of this post.
45 comments
Dude, your wife must really love you to go through all that which was obviously of way more interest to you than to her! I mean, I'm not married (maybe that's the reason), but any woman I've ever been with (that wasn't already technical) would have rolled her eyes and dismissively declared "Whatever!" and walked off by about the 1/4th of the way through the above dialog. I know, it's happened more at least once in my past! :-)
— Mike Schinkel on Monday, September 04, 2006 at 02:52 AM #
this such a sexist and stupid post!
— p on Tuesday, September 05, 2006 at 09:57 AM #
That is the Best description of Rest Ive read! Now I get it - I used to think it was just another competing way of getting information like RPC, SOAP, etc. But I understand from your article that it is a universal way of mapping information - I will start developing this way now!
— Jeff S on Tuesday, September 05, 2006 at 01:09 PM #
Ingenious way of describing it. Thanks for helping to clarify it for all of us.
— greg on Tuesday, September 05, 2006 at 04:39 PM #
Great explanation, Ryan... This is one of the simplest explanations of REST that I've come across. Thanks for making it available.
— Jay Jones on Wednesday, September 06, 2006 at 04:32 PM #
p: Ugghh. I have to admit, this post does seem kind of sexist now that you mention it. It never occured to me that it might be taken as such. I didn't mean to imply my wife was a layperson due to her being female. I use "explained to my wife" at work as a simple way of saying that something is being described in a way that you might be able to explain to layperson (like people who make buying decisions :) Of course, everyone at work knows that my wife is non-technical and also that she is one of the only people outside of work I get to have grown-up conversations with.
It's way more complex than that -- you could write a whole post on it.
There's a bit of context missing from the beginning of the post: I had been busy at work and hadn't seen her much in the past week or so. When that happens she starts getting jealous of the laptop and wants to hover over my shoulder -- that's a sign, it means: put it down and pay attention to me. If I don't heel to that hint, she'll start asking me about whatever's on the screen. If I'm lucky it's
vimand a terminal runningscreen, which freaks her out and she leaves. Otherwise, I'm usually in the browser or my newsreader. It just so happened that at this time, I was reading Roy's Bio so she saw his picture and says, "Who is Roy Fielding??!?," using the exact the same tone and inflection you might when saying "WTF?"When this happens, I usually just say, "Oh, it's nothing," or something like, "it's just some stuff about a thing."
Anyway, the funny thing is that I wasn't really trying to explain anything at first. It started out as a bit of joke -- a be careful what you ask for type thing. But then she says, "Oh, I get it." and I so I kept on going and the next thing I know we're talking about polymorphism and URL canonicalization and all kinds of crazy shit.
She gets me going on purpose just so she can see my arms waving and the vein pop out of my head while I'm trying to describe this stuff. I don't think she really pays all that much attention to what I'm actually saying.
— Ryan Tomayko on Wednesday, September 06, 2006 at 06:20 PM #
Awesome. On so many levels. The explanation of REST is excellent, and despite having been delivered to a non-techie, detailed enough for the technical reader who isn't passionate about the subject.
As for your last comment, the hovering, the vein popping and the grown-up conversations are an uncanny reflection of my life. I also get, "why don't you just get married to the computer," when she's had enough of me geeking out during non-work hours.
— Steve Collins on Wednesday, September 06, 2006 at 08:11 PM #
I think your page is fine. Nice basic description of the architectural style. The more I learn about it, the more difficult it's becoming not to get dragged into controversy. I don't think your page models a sexist scenario. Your wife could easily have been a child who just wanted to learn more. Not that I deny the existence of sexism. No way. It exists and it's damaging. But I think you can relax. Nothing wrong with being a nice guy.
— chris p on Thursday, September 07, 2006 at 02:07 PM #
Thank you very much for your effort to provide all those information, in your blog, and in SOA Yahoo! group specifically. I am one of your writings fans. I am trying to study SOA and really is so interested in your writings. Thank you
— Haitham on Monday, September 11, 2006 at 09:32 AM #
I didn't think your post was sexist. For Pete's sake lighten up people! Fact is, it's a very common scenario as described in this post. If the author would have pretended to be a woman explaining it to her non-tech husband, it would only be patronizing, if anything, and you'd have to be naive to buy it.
As a matter a fact, I think it is sexist to proclaim that this post is sexist, because the sexes of the people is not the topic and shouldn't matter, either way.
my 2c
PS I can't end my post without saying something actually related to the topic of the post: excellent description of REST! Well done.
Pierre
— Pierre on Monday, September 11, 2006 at 12:03 PM #
bravo! a great introduction to REST turned insightful (and subtle) polemic. I came here from the wikipedia entry on REST and must say that whoever added the link to this article had the right idea.
— ivar vasara on Saturday, September 16, 2006 at 03:48 AM #
I'd like to echo ivar's comments. Ryan's REST analogies worked for me and I too found it via Wikipedia.
— Kevin Howard on Wednesday, September 27, 2006 at 09:00 AM #
Nice. This is something my wife/kid/friend/dad/mom/brother/etc. could understand.
Why is sexism in this post important?
— Dave on Thursday, October 05, 2006 at 05:00 PM #
Really an interesting post, resembling Beateson's dialogue with his daughter... Finally I started unterstanding REST, thanks to you.
Grazie, as we say in Italy.
— Federico Gobbo on Friday, October 06, 2006 at 05:33 AM #
Great explanation. Thank you very much, REST is not that easy to understand.
— Bruno on Friday, October 13, 2006 at 12:00 PM #
this is great:) reading the questions out loud in a high squicky voice really helps reading the whole thing without quiting:) reminds me of when i explain stuff to my girlfriend:)
I can see how this could come off sexist, but hey, its not like the guy said "women never understand complicated stuff". there are a lot of people who don't understand computer stuff that easily. some of them are woman. it doesn't mean that they are stupid. but even if they were, we still love them and have the patiance to explain stuff, and they have the patiance to listen to our boring explanations about stuff they don't care about. that's love. and that's why i find this post actually romantic. i really do.
— Pizza Dude on Tuesday, October 17, 2006 at 01:05 AM #
that was fantastic. even me being a techie, didn't have much context of intricacies of REST. Thanks for explaining to all of us. I'm sure this'll help me in my further reading. And Kudos to your wife.
— SomeInternetDude on Tuesday, October 17, 2006 at 05:33 PM #
creative explanantion....finally some interesting reading.
— henry on Tuesday, October 17, 2006 at 07:57 PM #
i liked your post. i'd like to see you try to explain SOAP to your wife. i have a feeling that conversation would be incredibly painful.
— frankzappa on Tuesday, October 17, 2006 at 08:54 PM #
Thanks for the great intro to REST! I'm a girl, a nurse & just getting into IT, so it was PERFECT...& I didn't think it was sexist at all. I totally understood the context & have these types of conversations on medical topics w/my husband...way to relate when you are absorbed in your work.
— Kim on Tuesday, October 17, 2006 at 09:12 PM #
I think the Rosettanet framework has such a definition of how machines can talk to each other.
MS Biztalk has the RosettaNet framework implemented (in part) ... and allows machines to talk to each other. That was in 2001. And knowing MS, there are probably other more effective ways of doing it already. ;)
— Snappy! on Wednesday, October 18, 2006 at 04:18 AM #
Like the other readers commenting here, I love this and it helped me GET it (pun intended, har har).
But I wish you could expand on the last part, the part that you yourself said you don't get: "Instead, the large majority are busy writing layers of complex specifications for doing this stuff in a different way that isn't nearly as useful or eloquent." ... Why? ... "I have no idea."
OK, so you said you have no idea, but it would be great to read more on this if you do get an idea, so we can understand, are these people (I may be one of them) working in a different space where REST doesn't apply, or are we just truly clueless, or are there other forces in play that tip the scales to non-REST techniques, and are those forces appropriate ones (technical) or inappropriate (desire to perpetuate some walled garden somewhere).. what really is going on?
Now that you've provided some baseline clues for some of us, I really look forward to the next step where you expose and slice through the presumably flawed thinking behind non-REST approaches -- once you get an idea what that thinking is. This would help me, at least, understand this a lot better by putting it in context. Not sure if that made sense but I hope you understand what I'm wishing for.
— Jed on Wednesday, October 18, 2006 at 04:20 AM #
Hey Ryan,
Great post. I still haven't read the whole thing (i usually read the comments first ;Þ), but i really like the idea and the thought. Oh and i dont think that it should be considered sexist. It was, like you, or someone else, said, being explained to your wife who happens to be non-technical. And i know how difficult / enriching it can be to finally get the other person to understand what you're talking about. Have done that a number of times with my friends, non-technical ones who want to learn about something new and the (semi-)technical one's who need a massive un-learning session.
But most of all, i like the part about someone mentioning that your wife must really love you to go thru all that. And that brought a lil smile to me coz my girlfriend also does kind of the same thing, asking questions along the way and listening to the whole thing with full interest. :))
— Kush J. on Wednesday, October 18, 2006 at 07:01 AM #
Bravo mate :)
— Ivan Minic on Wednesday, October 18, 2006 at 07:21 AM #
"... machines suck." That's brilliant.
— Rob Riggins on Wednesday, October 18, 2006 at 08:34 AM #
Sweetheart,
You're so wonderful. I just don't understand why some of these people who commented here are so mean to you.
At any rate, I have a special surprise for you tonight. Wink, wink. Nudge, nudge.
You know where to find me . . .
— Mrs. Tomayko on Wednesday, October 18, 2006 at 10:11 AM #
There's no way this wife exists. No way, I tell you! J'accuse!
Nice explanation, though. Well done. Cheers.
— Chris on Wednesday, October 18, 2006 at 11:59 AM #
"most important breakthroughs in the history of computing.
Wife: Why?
Ryan: Because it is capable of describing the location of something anywhere in the world from anywhere in the world."
Nope. IP does it.
— on Wednesday, October 18, 2006 at 12:12 PM #
Excellent POST, and I GET it ;)
It's an interesting way to actually promote the REST architecture, since what is really simple can be explained thoroughly with out context. I would challenge W3C people to explain SOAP this way.
As for the sexist claim, it's just another sign we're in a insane time but anyhow here is the solution: rename the article to "How to explain REST to your 11 years-old boy". This is actually what I will test myself with my son Hillel. He's already using Ubuntu so he will GET it ;)
— Philippe Joseph on Wednesday, October 18, 2006 at 12:57 PM #
"Nope. IP does it."
Nope. IP describes which specific machine is the host of the resource that you're looking for.
Not that IP isn't important.
If I have to call my wife, I call her cell phone. I'm looking for my wife, not her phone.
— sean on Wednesday, October 18, 2006 at 03:12 PM #
Found your post really interesting, and your wife very brave. Must be hard to keep up with you!Lol
— Isabel on Wednesday, October 18, 2006 at 04:44 PM #
I know that I don't have any way to prove that I am Ryan's wife but I just wanted to put it out there that the conversation did actually occur. As a matter of fact, I was ticked off when I read the article because I thought he made me sound like an idiot. I enjoy the fact that my husband and I can talk about a variety of topics and learn from eachother.
I was also a little offended by the post signed Mrs. Tomayko
— Shannon Tomayko on Saturday, October 21, 2006 at 02:16 PM #
Mrs. Tomayko, please ask your husband more about this topic. I hope you can probe what theories he has about why people don't use REST, and what they just aren't getting, and he will explain it so well that it will become a followup writeup here and we all can learn more.
In other words, please urge him to do a sequel! This is great stuff, and it would be great to hear more!
— Jed on Tuesday, October 24, 2006 at 03:13 AM #
This is easily the clearest description of REST I've read, a good primer for younger developers before they read the more passive-prose-laden descriptions (like the one at Wikipedia). Thanks!
— Bruce Alderson on Thursday, October 26, 2006 at 01:48 AM #
I read this post from start to finish, with an early outage trawling through Roy Fieldings pages. Thanks Ryan, brilliant! And probably technically more correct than more 'correct' technical documents - this human interface has not needed to request for a paragraph re-send. Blessings and greetings to your wife also.
A few posters have picked up a bit on the 'human' aspect of getting on with real development. "large majority are busy writing layers of complex specifications for doing this stuff in a different way that isn't nearly as useful or eloquent" 'tis a bit like going to war to bring about peace.
Sir Winston Churchill once said "Men occasionally stumble over the truth, but most of them pick themselves up and hurry off as if nothing has happened."
Cheers.
— Max Wohlgehagen on Friday, October 27, 2006 at 10:18 AM #
I really wish I had a girlfriend (i'm too young to get married :D ).. or even a friend who would listen to all my HTML/XML/HTTP and all web-related 'WHAT-NOT'(that's what my current friends call it :( ) stuff... till then, to speak my heart.. i have IRC and Yahoo! hehe..
neways.. this was a gr8 article from ur side, and I won't term it as sexist, coz ya.. as u said, u were like "explaining to a layperson", as my mom once was telling me how to buy the perfect vegetables.. i wouldn't term that as sexist. :D
And when you say 'What the Data will like', do you intend to hint towards a universal data format that all servers will understand, something that the HTTP protocol does not completely comprehend (we have various headers.. but that hardly gets us anyways). And then your complex layers of specifications one.. well I for one would certainly agree after having read the XHTML 2.0 Working Draft. It's already 200+ pages by now, and it has completely changed the way we used to write HTML. Generalization has been used to way new concepts in it. That apart.. at the same time with WHATWG and W3 soon to be colliding head to head, it sure is a matter that we are missing a very obvious point: Since there are so many machines out there, and a machine could contact virtually any other machine, it does spell out a need for a common data format.
Those were my thoughts, my opinion, but in the end, it was a great read. Excellent I must say, keep it up :D
Rohan Prabhu, rohan2koolNOSPAM@NOSPAMgmail.com
— Rohan Prabhu on Saturday, October 28, 2006 at 12:32 PM #
How about using the term spouse to avoid outdated inferences of gender?
A more extreme measure would be to use a gender neutral language that does not have words for his or her, like Estonian.
Great reading thank you.
— Erkki on Saturday, October 28, 2006 at 06:49 PM #
Thanks, I found this very helpful.
Still, though, I'm looking for another aspect of REST; I'd like to get some insight into whether object-orientation and OO backlash aren't a part of the popularity of REST.
An example will, I hope, illustrate.
I worked on a application a year ago for magistrates -- people who write arrest warrants. We used J2EE, and thus created magistrate objects, officer objects, offender objects, statute objects, and (of course) many, many other supporting objects. All this, we did, in order to render an arrest warrant that our magistrate wanted to print.
A RESTafarian would, I think, point out that in this application that just knits together a bunch of data for a printout, there's little call for OO. A RESTful architecture wouldn't have many objects, not for this app.
It seems to me that part of the attraction of RESTful architectures is that they avoid the compulsion to turn everything into an object. Does that sound right, or am I on the wrong track?
— Steve Metsker on Friday, November 17, 2006 at 07:57 AM #
Thank you so much Ryan, It was very nice explanation about REST that I was looked for.
— Mohammad Norouzi on Saturday, December 02, 2006 at 03:24 AM #
This is the fist blogpost ever I've read from start to end. You should create a series out of this. "Ryan explains things to his wife".
— August on Tuesday, December 05, 2006 at 10:44 PM #
Thank you Ryan for this technically neutral explanation. I was wondering the impact Web 2.0 could have in the near future on the IT domains I'm working on... This is the best source of inspiration I found so far!! I'll dream some more time about it...
— Chris13Jim on Monday, December 18, 2006 at 03:48 AM #
And, you wrote all this down while you were having this convo?
— EatMyShortz on Tuesday, December 19, 2006 at 09:18 AM #
A suggestion to make things look less sexist: Maybe your wife doesn't want her name on the blog, but if she's ok with it, try using her name (or first initial) in the conversation instead of 'Wife'? I think it would make it clear that she's a real person you're having a conversation with, not just the steoreotypical non-technical female.
— Laurel on Tuesday, December 19, 2006 at 03:16 PM #
I can see the resource.
Handle complicate thing need simple way.
Who is "Ryan Tomayko"? hehe
— Paofan on Wednesday, December 20, 2006 at 02:29 AM #
Nice article, but wrong in subtle and important ways:
You can think of [a URL] like GPS coordinates for knowledge and information.
That was true at the beginning of the web, but not since 1998. A URL gets you part of the way there, but not all of the way. Not since the invention of customizations for users, or returning different data based on the context of the request.
I'm afraid REST people think the web is too easy. The web is about more than nouns and verbs. Its about state and logic as well.
A lot of Web 2.0 APIs think that since blogs and wikis have permalinks, then everything can have permalinks... and therefore a REST-ful API can be used for a majority of the web.
I'm just not one of those people.
I need more than 4 verbs in my language.
— bex on Wednesday, December 20, 2006 at 05:04 PM #
Leave a comment