This is the third post (in a row) I’ve made about REST. I’ve now read multiple explanations of REST, many of which say the same thing. Then I see implementations of these explanations, and the people who coined REST turn up their noses. I know someone has implemented REST correctly. I mean, someone out there HAS to have done it right…right? Every criticism of why a service is not RESTful uses terabytes of nit-picking jargon but somehow lacks examples on how that service could be made RESTful.

“This service is NOT RESTful because in REST, payloads are self-describing and contain references to other resources, and servers should be able to change their namespace, and two points always make a line unless one is in hyperspace.” And xyz.com’s REST API wasn’t doing this? What could they have done to change this? What IS REST about their API?

Maybe I’m dumb. Actually, no I’m not. I just can’t look at a spec and say, “Oh, I get it.” I have to see real, live examples. Why can nobody do this? It seems every HTTP “REST” service is a false implementation yet nobody can give a concise explanation of why.

I get that using only GET and POST is not RESTful. I get that every resource is a noun, and has a URL associated with it. I get that verbs are defined by HTTP and should not be used in URLs. I get that HTTP status headers should be used in conjuction with responses. I sort of get what a media type is (application/vnd.ieatmcdonaldstoomuch.cheeseburger) but do not get where it is defined. Or is this arbitrary?

Some points I have taken from all the back-and-forth involved in trying to break into an extremely elitist (and rightfully so, REST is REST) architectural style:

• REST is stateless. All information required to complete the request is sent with the request. Every time.
• REST re-uses existing specs. HTTP has defined some very useful verbs (GET/POST/PUT/DELETE) for us to use. It makes sense to use those instead of creating custom verbage. HTTP also has status headers for letting a client know WTF is happening. 200 OK, 506 Suck My Balls Client, etc.
• REST maps resources to locations. I can find events by doing GET /events. I can post an event by doing POST /events. I can delete an event by doing DELETE /events/123. These URLs (/events, /events/123) are resources…an event collection and a single event. They are abstract things and a description of that thing is what is interacted with (aka “representation”).
• REST uses media types to define resources. I’m assuming this is the “application/vnd.event+xml” content-type thing. This is very confusing for me. Where is this MIME type defined? How is it defined? How does a client consume it? WTF is going on here? Any ideas, anyone?
• A REST service is self-descriptive. Reading one of Roy Fielding’s annoyingly-complex criticisms of bad REST implementations brings up the point that given an initial URL and a “set of standardized media types that are appropriate for the intended audience,” I should be able to completely discover all information on that service. So when I hit the homepage, I should get an XML/JSON/HTML response telling me that there are events under /events? How do I structure this response? What “media type” would this resource be? I get the point behind this, but would love to see a full implementation.

So while I’m have a lot of trouble grasping the last two points, everything else seems to make good sense. So far, anyway. I’m sure in a few minutes I’ll read another guide telling me that everything I know about REST is WRONG and I’m going to hell for even thinking the word REST without knowing exactly what it means.

Perhaps a REST web service that describes how to implement REST over HTTP would be a fun and amusing project…

UPDATE – I suppose a website comprised of HTML that describes REST would be RESTful…no need to make a “service.” Maybe this should be taken under because there seems to be a vague disseration, a few authoritative “resources” who love to use useless jargon, and a collection of blog posts that individually are all wrong, but pieced together create a somewhat workable view of that REST over HTTP should be like. So, someone should definitely get on that. In fact, I just might.