Turns out REST APIs weren't the answer (and that's OK!)
Vložit
- čas přidán 23. 06. 2024
- A decade ago, it seemed like everybody was talking about ReST APIs and HATEOAS, blog comment threads bristled with spirited debates about whether something was, or was not, a REST API, and we all thought hypermedia was the key to building long-lived APIs. And yet here we are, a decade later, building just as many APIs as before but seems like hardly anybody's talking about hypermedia... so what happened?
NOTE: At 8:14 or so, you can hear what sounds like a cat in this video. I am absolutely baffled as to where this came from, as there weren't any cats (or kids, or anything else that might have made a weird meowing squeaky noise) anywhere nearby when I was filming this. I've decided it must be a Ghost Cat: one of my cats who's no longer with us is now haunting my OBS installation. Let's see if they show up again in any future videos.
Links:
Roy Fielding's dissertation "Architectural Styles and the Design of Network-based Software Architectures":
ics.uci.edu/~fielding/pubs/di...
Roy Fielding: "REST APIs must be hypertext-driven", October 2008:
roy.gbiv.com/untangled/2008/r...
Hypermedia Formats:
SIREN: github.com/kevinswiber/siren
HYDRA: www.hydra-cg.com/
JSON-LD: json-ld.org/
Collection+JSON: amundsen.com/media-types/colle...
HAL - Hypertext Application Language: stateless.group/hal_specifica... - Zábava
That mismatch is the reason why most people call it RESTful today.
I once saw a YT comment calling REST a "RPC with extra steps" and this stuck to my head... it really is just RPC with extra steps
If you completely misuse it, yes it is.
more of this please. More explanations re: the difference b/tw the standards, the intent of their designs, the hazards of using them, the hazards of not using them, the hazards of not using ANY of them, and more info on how folks just "roll their own" and why that's good & why that's bad.
The "tuning in" part at the end was great. I'm rattling my brain on similar phases that are more symbolic than practical now. Could argue number dialling is one. Great video either way :)
I like "hang up", referring to ending a telephone call - that one goes all the way back to the days when telephone handsets were actually wall-mounted, so you literally hung the handset up... then "hang up" became synonymous with "put down" when telephones switched from being wall-mounted to being freestanding on your table/desk, and now it means "push the bit of your touchscreen that's currently showing the 'end call' button".
@@DylanBeattie not to mention that the universal icon for saving is still a good old floppy disk ;)
@@jayishappy "Save file" is a floppy disk, "open file" is a yellow cardboard folder, suggesting that somebody runs around at night printing out all the documents from the floppy disks and putting the printouts in the yellow cardboard folders.
Skeumorphism is *weird*.
@@DylanBeattie as it goes with radio buttons (from actual radio devices), menus (actual restaurant menus), icons (religious paintings), calculators (from calculi, small pebbles). Metaphors (from to move across) really are the engine of language and it's fascinating (I recommend "The Unfolding of Language", by Guy Deutscher, to anyone interested in human language evolution)! I think we only notice the original meaning in those words for which we aren't young enough.
Goodbye originally meant god be with ye
Love that your CZcams videos are as well researched and full of background as your talks, another awesome video Dylan
This, 100%
I've been using and creating APIs for well over a decade and somehow I never knew about the hypermedia stuff.
Now if you were to send the "Login" button itself instead of a json saying there should be a button - you get HTMX. It exposes the ability to request HTML elements themselves and layouts them in, which can then request more, different elements. The most web native hypertext solution possible, no protocol negotiation beyond "do you speak HTML". You just get sent the finished button.
But muh separation of concerns!!!
Returning an application error in a 200 response is a valid choice. Why overload the transfer protocol signaling when you can and should handle the application error gracefully, and let the application domain remain loosely coupled.
REST for me was always about CRUD and defining the data taxonomy in the URL path. Sometimes you added extra data, sometimes that extra data was trivial to compose so didn't need to be sent. You did whatever made the API as clean and stateless as possible because that is what matters for scaling the backend.
At work, we've got a 3rd party API that goes one stage further than returning an error message with a 200 code.... it returns NO error message and a 200 code.... even when your request has failed... neat huh?
Salesforce Marketing Cloud messaging API returns a 200 and success response for improperly formatted mobile numbers and then doesn't send the message!
I think it is apt that HATEOAS begins with the word "hate" in uppercase, because that pretty much describes my feelings towards it :) I find that writing a frontend for a true HATEOAS API is a lot of unnecessary extra work with loads of additional requests, whereas I enjoy that when I write my own backend, I can build massive JSON structures that delivers exactly what my frontend needs.
And yes, that might introduce a slightly tighter coupling, but I prefer that APIs (be they network request or objects and methods) are designed to limit the workload of each other, rather than to achieve some lofty architectural ideal! But of course, that is an opinion :)
Well, those pushing the idea ignore the simple reality that real world apps end up with a ton of data they don’t need, and making a ton of calls to get the missing parts. And the idea that I can write a front end through the backend is at least next to stupid (more likely fully into MORONIC)
When I see the acronym HATEOAS, I often think "Aw, they've simply mis-spelled Halitosis."
I never figured out how to actually consume a REST API. I get links back, but usually these links are formulated in a way where coercing it into a shape that is suitable to be fed back into the HTTP client is a lot more work than just putting the paths in the code instead.
You need to parse the result and display the result dynamically using links, buttons etc. To be able to display the results in a user friendly format you need some sort of directives in the response to specify placement, colour etc. So basically you need to develop your own version of a browser, markup language and css type language. Hint: we already have these things, just use them. Arguing if something meets someones definition of a REST API is a waste of time
The alternative to rest was soap. Once you add HATEOAS, the simplicity advantage of rest evaporates but you still have the lack of tooling.
I used to weasel my way out of it by using the term "a REST like API'
I go for "resourcefulness" often. I think the decent idea there is turning verbs into nouns or in other words recording events as facts; aiding full fidelity of information without duplication.
Like some of the other commenters here, I've never come across the hypermedia aspect of REST until this video, so thanks for educating me on that. As for whether I'd be adding it into some of the APIs I've built....probably not. For me the main benefit of REST is that it's a very standardized way of fetching and editing resources while also being fairly lightweight. A tool like swagger seems to make an actions section of the response entirely redundant, because realistically all that would ever be is just documentation for the developer consuming the API as they write their client, once it's actually running, the actions would almost certainly be ignored. I can see a potential benefit to having links for paginated results, but in the past I've just had my endpoint take page size & page number as optional parameters. Next and previous links could be a nice touch, but more of a minor convenience feature than anything that actually substantially changes how clients interact with the API.
It's possible to use a wrench to hammer in a nail. We all tend to fall into to the "Shiny New Tool for Everything" trap. Remember what your dad told you: "Use the right tool for the job".
REST lost its meaning for me long ago. Tons of pedants running around trying to define it in different ways has left me thinking: “it’s just an API”
I remember when HATEOS, and hypermedia driven API's in general, were the darlings of framework developers and architecture astronauts; however, even during their heyday it was obvious to me that these ideas wouldn't survive contact with reality - they added a lot complexity (and thus development time and expense) while having little practical benefit for most applications.
i actually implemented the HAL RFC draft for one of our backend APIs to enable HATEOAS. being able to reference related resources in the response, but also giving clients the ability to request the embedding of these resources on the fly turned out to be really useful. but so far i think no client implementation really uses the links to discover actions.
It's easy up until the hypermedia part, then it's a big old grooooaaan
I always found those pushing hypermedia to be hyper full of themselves solving problems that don’t apply to a real world.
From the OpenAPI specification: "The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs..." So there you go: "HTTP API". It might or might not be RESTful. Usually it is not. I usually call them just HTTP APIs or HTTP-JSON APIs when talking with developers who at least should know their stuff. And I might call them REST API when talking with people who use the word REST without knowing what REST actually means.
This is superb Dylan! I shall share it at will next time someone says: "It's not really ReST". Oh yes, and very chuffed to have been a small part of the motivation for you to click "publish" on this ;)
What a lovely take.
as far as REST-adjacent patterns: I don't think I've ever written a single API that faithfully adheres to what RESTful actually is... For example, I constantly break the POST/PUT pattern - for me PUT is create a resource, PATCH is edit a resource, and POST is "perform some specific action against a resource", and that's *definitely* not RESTful, but it comes up a lot...
And that's fine - I think what matters is Consistency and Documentation.
(it helps also that every API that I've ever written has been self-documenting through a REPORT method to the same url as a kind of side-channel)
And for me, I use post to create resources (my reasoning is that if the result is not identical after two requests than it is not a put), I use put to set all the data in an resource (this way even if someone somewhere changes something the result of calling out again is the same), patch for updating specific values in a resource (the ones I passed in the request), get for get, query parameters for query, etc
Because of my constraints, I very rarely use put, I use post a lot for creating resources and lots of patches and gets
For documentation, that's what OpenAPI 3.0 is for.
The JSON APIs at my work are definitely not REST. Not only is there no hypermedia, almost all of them are actually RPC rather than representing resources, because we don't build CRUD APIs. We also don't use e.g. jsonrpc. I'm pushing to just switch to gRPC but people like to use what they are familiar with.
There's nothing inherently wrong in modelling RPC's as an HTTP POST with JSON bodies in both request and response. The common REST frameworks can easily handle this, so why not use them if that's what the developers and users are familiar with?
Yeah the issue has always been there's no point to the hypermedia part for most APIs. Nice idea, but impractical, difficult, and pointless. So REST in the IT business world just naturally became about having something better than SOAP to create, update, and read data remotely. I think it's fine to call these kind of APIs REST, or RESTful. Everyone does.
Very interesting and well explained summary.
Awesome video. My personal opinion... REST is the dumbest possible solution to the problem of "client code wants to run server code". I feel like we've stepped backwards. Give me RPC with autogenerated client-side proxy stubs so I never have to give a dam about the network implementation. The real solution is not to use HTTP for this kind of IPC. I want a dedicated protocol that web servers can utilise alongside HTTP.
Soap is a damn mess. I hate it.
Graphql is a damn mess. I hate it.
REST is great. Simple and, if you respect the HTTP rules(?) (ok, created, accepted, ...), absolutely solid.
EDIT: except 404 Not Found - so entity not found. But because the route does not exist, or the entity in the entity list does not exist.
And responses should be JSON only.
Did i mention that i hate graphql?
EDIT: except 404 Not Found - so entity not found. But because the route does not exist, or the entity in the entity list does not exist
IMHO the restful answer to that is that to the client its a distinction without a difference. Routing is an internal matter on the server side. The 404 response just means there is no entity with the URI that you have supplied.
@@barneylaurance1865 Makes sense. So internal problem - internal code, like x-header or data[code] i guess. :/
I'll argue that the correct response when there is no data found is HTTP 204 (No Content) or HTTP 200 with an empty dataset in the response body. The request format was valid, and the server successfully found nothing. The server cannot know whether or not the user made an error (like specifying the wrong entity ID), versus intentionally checking whether or not that entity existed; therefore, it would be wrong to use a 400 series error here. A 300 and 500 series response would make even less sense. A 200 series response makes the most sense.
Then 404 can be reserved for when the user requests a type of entity that doesn't exist.
@@Dennis-vh8tz NOOOO plz dont do that :D "the server successfully found nothing" -- you cannot return success on failure. =)
404 is often purposely a lie. Telling you it doesn't exist rather than telling you you're not allowed to look at it. A layer of security by obscurity on top of a layer of actual security.
8:15 I think your cat doesn't like Swagger
My apologies for having anything to do with SOAP
To me (and I know this is in conflict with Roy Fielding's definition) the defining part of REST is that the requests contain the state of the application (so servers don't need to maintain any per-client state between requests), which enables caching and horizontal scalability. I don't really care about the rest of it.
See, that's the frustrating thing... I don't think your definition *is* in conflict with Roy Fielding's definition; it just doesn't go far enough to satisfy a purist definition of REST. In his dissertation, Roy's derivation of REST explicitly has a stateless constraint (5.1.3). The six prerequisite constraints for REST - client/server, stateless, cachable, uniform interfaces, layering, and code-on-demand - actually form a pretty good set of constraints for building any kind of HTTP API, and I think a lot of folks over the years have, consciously or unconsciously, conformed to those constraints, created a system they consider to be RESTful, and then get a bit of a shock when the purists take them to task over it for not having hypermedia controls.
"I don't really care about the rest of it" is a great presumably accidental pun.
@@DylanBeattie Perhaps it is the purists who are making an error - specifically conflating REST and HATEOS. If REST required hypermedia controls, there would be little if any difference between REST and HATEOS, rendering the terms redundant. In contrast, omitting hypermedia controls from the definition of REST makes the terms significantly different from one another.
web turned successful: "citation needed" LOL ;)
In most cases the hypermedia is useless, because something will be programmed based on the spec rather than reverse engineering from submitted responses. Links could perhaps be applied if the API is designed to be called by a presentation layer, but that's the only case I can think of where it might have a use.
Do you think there's an argument for redefining rest to mean Richardson Maturity Model Level Two (the level just before Hypermedia), as described by Martin Fowler on his website in 2010. That may be closer to the common usage. And then we can talk about HATEOS APIs for level three, which is what Fielding calls Rest.
I absolutely think there's a case for adopting a term to describe RMM level 2 APIs that doesn't have hypermedia controls as a prerequisite. Whether that term is REST or OpenAPI - or something else? - is kinda the question that inspired the video. To me, everything up to RMM level 2 has always been about applying design patterns based on HTTP itself - and most folks who do that end up with similar and broadly interoperable implementations, some of which include links, which I think works pretty well. The point where I think it usually falls apart is hypermedia *actions* - once you go beyond GET into PUT/POST, things get a lot more complicated.
@@DylanBeattie Right. And without going back to look at the dissertation again I'm trying to work out how it even can make sense to say it's not rest if it doesn't have hypermedia. We don't say a web page is not a web page just because it doesn't have links.
Maybe it's just that links join what would otherwise be multiple APIs together - so what would be one rest API with hypermedia technically becomes a collection of many separate rest APIs if you delete all the links.
In principle full HATEOS rest should enable APIs including links to resources that are part of APIs provided by totality separate organisations, but I don't remember ever seeing that.
@@barneylaurance1865 If it isn't in 6nf it's not a real database!
Regardless of Roy Fielding's intent, I think this is what REST and HATEOS have come to mean. I wouldn't use OpenAPI as a synonym for RMM2 as the terms address completely different things. OpenAPI isn't a type of API, but instead a standard for specifying an API. The exact same API could be specified using different standard, like JAX-RS.
Your API is a crying shame, you give REST a bad name!
Hall of shame, but yes. It falls apart, and we take the blame.
@@barneylaurance1865 You promised me JSON, then sent XML. 😞
Woh wu wu Woh wu
Woh wu wu Woh wu
Woh wu wu Woh wu
Woh wu wu Woh wu!
Background noise: cat in heat or small child? 😂
You know, I have absolutely no idea. No cats or children on the premises. I didn't even notice that until somebody pointed it out on the recording...
REST will be around in 15 years .... just like Javascript, we are stuck with it. I don't mind it. I like the ask receive nature of it.
this channel is a rare gem
SOAP - was an oxymoron. Simple .... 'nuff said.
I often wonder how that protocol was invented, every developer I every met hated it the first time they saw it. Although, from memory, it was organisations like IBM that promoted that protocol.
I'm a bit confused. Why is OpenAPI mentioned at the end of a list of REST, GraphQL, and gRPC? OpenAPI is just a description language for REST APIs. It shouldn't even be mentioned once in the entire video.
i like the term REST-like
That was an amazing video. Sub'd, like'd, and now commenting for the algo.
Also, SNMP. Four lies in one acronym. :D
You mean the simple network management protocol that isn't a protocol, isn't simple, and doesn't manage networks? Yeah. Love that one.
I've been a professional software engineer for over a decade and have worked at several companies, and in my expedience so-called "RESTful" services is the software version of "We're Agile, but..."
It seems to have evolved into a genetic umbrella term that conveys the general idea but doesn't necessarily conform to a consistent standard.
What was the Question?
How could you leave htmx out of this video?
While I've read most of Carson Gross's essays and articles about REST, hypermedia, HATEOAS, etc, I haven't done much with htmx beyond "hello world".
On the timescale we're talking about, though, I don't think htmx has been around long enough to have had a significant impact on the way we build, and talk about building, APIs. REST dates back to 2000, SwaggerUI first shipped in 2010, and htmx 1.0 was the end of 2020. If it sticks around (and I think it might!), I'll make another video in 2034 talking about how htmx revolutionised API design. Promise.
@@DylanBeattie For a lot of webdevs of our generation, Gross is THE RESTafarian lol
I haven't used htmx in a project like ever, but it's influence is already so large if I ever know of concepts like HATEOAS etc it's because of it
How my watching went : "what is this guy even talking about, whole world is sitting on top of rest apis..."
....
"Oh he's gonna talk about ACTUAL REST" 😂😂😂😅
But graphql and grpc can still be rest, they are just middleware to enhance basic http communication. However, they don't really go against the rest principles.
From a consumer of a lot of web APIs, REST is by far the easiest - the tooling is there, it's easy to understand (syntax, documentation) and all languages support JSON (or Xml). I cannot really think of a suitable alternative - there is GraphQL, but this is an absolute mess, which is difficult to understand, has a syntax which is not JSON compatible, and has limited language support. I can understand some of the complaints of REST (e.g. over-fetching), but where this is a concern, it can also be remedied easily.
Spot on how ppl misuse the term REST API.
btw, I think Hypermedia doesn't make any sense at all. It might have well intention but has no real usage in reality.
Ok , i guess i was working with openApi. Works fine for CRUD. So i will just keep going on.
Genuine question : "Hyper" - why? Why Hypermedia, Hypertext, Hyperthirdthing - why was "Hyper" used in the context of the internet?
It all dates back to a really influential paper by Ted Nelson from 1965 about structures of complex information systems, where Ted coined the terms "hypertext" and "hypermedia" (and, I believe "hyperdata" as well, although that one didn't stick as well as the other two...)
dl.acm.org/doi/10.1145/800197.806036
@@DylanBeattie Perfect answer, thank you so much!
I'll be the weirdo here, but personally, I never really liked REST APIs. They're good for simple objects and CRUD operations only, but any time you try to represent something that doesn't fall within that realm, you're producing kludgy nonsense. Personally I'm more of a fan of RPC over REST.
You're not alone :) BTW, another thing I don't like about REST APIs that they tend to push business logic to the frontend. And the languages we use on the frontend (practically, JS) are usually not really a solid choice to implement business logic...
You're not wrong, but there is a vast universe of use cases that can be satisfied with simple objects and CRUD operations and it's wise to start with a lightweight framework if there isn't an obvious reason not to.
@@fang_xianfu I know, I just don't find it a good fit for most of the stuff I tend to work on. I'm currently doing storage and backup automation/reporting. Simple CRUD does not satisfy our needs, yet we still went with "REST" because:
* that's what everyone uses
* it's simple with django-rest-framework or flask-restx
* it integrates well with Swagger (OpenAPI)
Which I think are all poor reasons to use a CRUD framework for an RPC coding style.
HAHAHA, we're still using SOAP
JSON Apis that try to have links and stuff are just the worst lol.
There are different tools for different jobs.. The statement isn't "REST wasn't the answer. " It just isn't the answer for everything, and never was claimed to be. The semantics don't mean much to me at least.
Things are named what people call them, not the other way around.
Aww man, give it a rest will ya 😂
I've been screaming about this for years. You can pass the majority of parameters on the fricking URL. Or use http post. REST APIs just add more wrapping to the data which needs to be unwrapped. My simple PHP web application was 175 times faster by not having to wrap and unwrap data with JSON. You're just adding more overhead.
8:14 great video, now show your cat please 😸
Just callt them webapp and webui and implement the clients needs already! Enough with the mental instant gratification...
My teammate told me returning null with 200 OK is restful
Hypermedia controls? Is that always HTTP requests?
Unfortunately language does what it's going to do, and you can't really hold back the tide. I think it would probably be better to make a term for APIs that use hypermedia specifically and a word like "OpenAPI compliant" for the middle ground and just go along with it.
Martin Fowler should be put where he belongs, that is in the place of someone making money be telling and not doing. And in his statement on definition of REST - well he needs to spend more time in language arts where we learn that definitions change over time.
I’m curious if you intentionally didn’t mention HTMX. Doing HATEOAS with HTML makes a lot more sense to me than doing it with JSON because we don’t need to synchronize client state and server state, considering JavaScript isn’t doing a bunch of element creation. HTMX is great because it extends HTML as a hypermedia beyond just the anchor and form tags. It’s a very simple yet powerful idea.
i build APIs with only GET method without building POST endpoints, and use query params to represent the params passed in, and its simple and works well. just like how unpure function calls can return different results, HTTP GET idempotency doesnt really need to be adhered to
But then your request size is pretty heavily limited isn't it?
@@elijahbuscho7715 yes agree with you, I havent build any file upload endpoints yet, that's better suited with POST endpoint and formdata object
Imagine wearing a shirt from a megacorporate code forge that wants to make software into social media website & that requires an account to make upstream contributions to projects or even use search on code.
I'm gonna print this comment onto a shirt and wear that in my next video.
All very Gödelian ;-) You can't prove Rest within a Rest framework. It's like pure maths arguing with applied maths.
imo hypermedia in APIs is just bloat. If the API is well documented then the links are worthless and the consuming code probably doesn't care. The only thing they do is slow down the response time.
lol you sound like an old person saying the old movies are better