tef

bad poster & mediocre photographer

  • they/them

here's a brief history of the term "restful" came about:

  • having to use different email clients and different file server clients for each and every service sucks ass
  • here comes the web browser: without having to download plugins, i can go to webmail, i can use a forum, i can share files, all with the same program.
  • you can click "open in new tab" halfway through a list, and not lose your place, which is kinda cool if you think about it.
  • [thesis voice] what if we called that detail "representational state transfer"
  • let's write a really impenetrable thesis about how cool it is we can do this, and what sorts of constraints got us there

[two hours later] people discover the thesis and re-enact the fall of the tower of babel:

  • hey, this "one client for every service" thing is cool, let's write a million different apis which all need special unique clients, and call it "restful".
  • you're wrong, i am 100% sure that using rest means "make it look more like webdav". everything must be crud. here is 100 page spec on pagination in json.
  • actually, never mind all that. what if we had one browser per website instead

as much as i think about grabbing a broken table leg and screaming "WHERE IS THE REPRESENTATION OF STATE AND HOW IS IT BEING TRANSFERRED" there isn't much point:

  • the term 'restful' is a complete lost cause, there's no real immediate benefit to having a precise technical understanding, and the misconception is far easier to understand
  • the loudest advocates for '100% original thesis restful' are often just as wrong as everyone else, as they still don't end up with "a thing you can use a browser with"
  • people started using 'hypermedia' instead, but in practice it's almost as ill defined, with long running arguments about the correct types of urls and methods

the thing that's funny though? the thesis is a really bad way to understand how a browser works, anyway.

the thesis is actually about a methodology for understanding systems by means of layering constraints, using a browser as a key example. unfortunately, this methodology doesn't really seem to work, given that no-one actually understands rest or restful very well.

to the point where the name 'rest' now means something entirely different. it's almost as-if the thesis itself is anti-mimetic.


You must log in to comment.

in reply to @tef's post:

Versions I've encountered people saying to me with a straight face (non-exhaustive):

  • HTTP with JSON
  • HTTP with JSON, and also you use PUT for actions instead of POST
  • HTTP, with an identifier in the path
  • HTTP, using only GET, PUT, and DELETE

i have had a coworker "design" an "api" that:

  • randomly jumped around where endpoints were (the same resource would be at like, /resource/id but then to get a subcomponent of it would be /resource/component/id and sometimes /otherthing/resource/id )
  • sometimes returned json
  • sometimes returned html embedded in json
  • sometimes returned html directly
  • used a different format for input and output on several fields
  • stateful returns

i wish i could say i was able to block all of this but :| i swear some people get paid by the line

I feel like I have the "no, you return structured semantic data, not HTML, not fucking raw bytes you slurped directly out of the DB, and if you try to return live JavaScript I will have you killed" conversation on the daily. Just holding that fucking line is a nightmare.

the fun part is "returning live javascript" is still restful because of the optional "code on demand" constraint

and well, rest it isn't really about the exact content-types you return, or the precise means by which you expose hypertext controls,

just that you use something standard and known to the client in advance

I’ll be honest: I never learned whatever “original” definition there is precisely because “REST = HTTP+JSON” is how every employer/project I have worked on in ten years has used it, and so as you say, any other definition feels more likely to confuse than assist understanding.

As is often the case, the use becomes the meaning. Kanban means Trello now, agile means your manager goes to a lot of seminars, sprints mean we set arbitrary deadlines we never follow.

this is entirely unrelated to the post but i had a bizarre amount of difficulty understanding which words were in the post and read the title as "reckful is antisemitic". maybe there really is an antimeme here; or maybe i'm just sleepy

If I took anything away from Leonard Richardson's 2015 talk "The Enterprise Media Distribution Platform At The End Of This Book" it's that actually-RESTful hypermedia-driven protocols are incompatible with capitalism. It's simply the wrong tool for the job for people who want to control both ends of the pipe, which is virtually everyone who gets paid to build software things that happen to leverage HTTP. I don't think that's the thesis' fault.

the thing is, html counts here as a actually-restful hypermedia-driven thing, and the sheer volume of browser based desktop or mobile apps shows that the ideas are pretty popular, even if not fully realised

in my opinion, the reason no-one's adopted "real hypermedia" formats is a grab bag of different factors:

  • people want to just glue shit together, not think about modelling their application state as an addressable resource store with semantically defined relations between them

  • things like rpc in json and http are just easier to implement, even if they involve repeating a lot of the same boilerplate, and implementing hypermedia is a bit too much of an up-front investment

  • things like protobufs and thrift make things easier for compiled langauges, both in the language and for interoperation with the language, and things like json kinda tell you to go fuck yourself

  • the "not html but hypermedia" options really don't cater to things outside of "it works like a filesystem" or "it's a database table being paginated", and sometimes you just have a bunch of rpc stubs to call, or a socket that sends log messages.

  • unlike html, you have to often have to write your own browser to navigate these apis

  • and well, if you make your html trivial to screen scrape, it's trivial to automate, and often a lot easier than working against a custom api