As a card carrying restafarian and an editor of the OpenAPI specification, I want to say thank you for your service. Clear, concise unbiased explanations are something we can never have enough of.
@@MrJoefinisher Or RESTful. But yeah, Dylan's right. We've moved on from the REST idea as originally designed, but that's totally okay, because without REST, I don't think Swagger/Open API could ever have existed.
Honestly, if your API has anything like a login, it's not a REST API. The whole point of REST is to have efficient intermediate caching. CDNs use REST. Nobody else does.
I totally expected something else from the title, but I got a video absolutely worth the time. Great summary of the status quo. And yes, people say "REST" when essentially they mean "I'm calling some endpoint that roughly follows the Swagger guidelines and I'm getting back some JSON".
Maybe. Or they mean "Representation State Transfer". The server maintains a global state and clients request representations of that state or update small portions of that state represented by a URL. State need not be a directory structure of hyper media. State can be a map of the Earth or a web shop or music catalog. The client cannot know all server state and the server need not know all details of client state.
@@familyshare3724 Yes, the two things are completely unrelated but have been conflated because both were designed to make communication between a website and its own backend easier, hence the two were usually used together. This has intertwined the two in most people's minds.
I think that's stylistic. To me, 200 OK means "the program didn't crash." e.g. it ran successfully but "you asked for a customer without supplying the customer ID" or whatever is a "supported" error condition -- the page will run (200 OK) but if you're going to get what you came here for, you're going to have to do something different. But to each their own.
@@kevinrusch3627We already have error codes for when servers crash (or encounter other issues), those being Internal Server Errors. Servers should return error codes like 500 when an endpoint, be it valid or invalid, results in the server experiencing an unexpected condition. Returning code 200 (OK) is confusing (and dare I say, objectively wrong) for an unsuccessful call because it indicates "What you have asked me to do was valid and I have done it." to the caller.
@@kevinrusch3627the frontend should be checking those things. So if that reaches the backend, it's a problem with the software (=frontend + backend) as a whole, so deserves an error code. 4xx codes are used for frontend mistakes, 5xx for backend mistakes. Crashes in the backend will always return a 5xx code.
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.
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.
Writing software is easier today, good on one hand for the short limited life span and bad in many ways. Example: If you write a piece of software today and it consumes a google api using some api link. I will guarantee your software will die the day that url disappears. Explain that to your boss 3 years from now when your application fails to run. I sometimes wish I had followed embedded systems engineering. At least if I engineer a toaster, that toaster would run until electricity flowed. These days, your toaster could stop making toast because googles toaster api was retired. This means, google owns your software not you. I chose not to embrace the puny weak hacked stuff. As you will end up with a 404 not found application.
"Representation State Transfer". The server maintains a global state and clients update or request minimal state by a URL. State need not be a directory structure of hyper media. State can be a map of the Earth or a web shop or music catalog. The client cannot know all server state and the server need not know all details of client state. HTTP error codes are useful in protocols generally: 2xx OK, 3xx go away, 4xx bad request, 500 bad server
REST makes everything simpler and predictable, much easier to develop and test. In theory a minimal request returns a minimal response without sharing each other's State. Call and forget. Any session token and state lookup always complicates things and should be kept to a minimum. "Do you have any widgets and how much do they cost?" Just answer the question rather than: who are you, what else are you looking for, why are you asking, have you been here before, how much can you afford, do you have a job, maybe you like turtles?
"difference between standards" between Rest and say SOAP? No. ReST is the only game in town, not just web pages over HTTP. Even RCP can be ReST. Are you sharing and maintaining (minimal) state or not? Suppose you develop a game. You might think the server should maintain all state and clients just ask for state. Maybe, but should the server draw the pixels on each screen, too? The client asks "how much money do I have?" but not "I have $1 million". The client says "I move forward" not "I am in the castle" nor "this is my entire reality" nor ask "what is my entire reality?". Rep State Transfer: C: I move forward. S: you cannot. C: I move left. S: You see a chair. C: I sit in chair. S: Ok. C: I kick chair. S: you have 50% health, the chair is at x, y, and you see a gold coin
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.
I feel is all sbout selling cloud... Need a more safe model to sell , model timeshare cant works. Hence refactoring bybthe goodbold category theory with monads andvlogic topology... Hence no acid crud butbbase crud😊
Many 'Restful' APIs have difficulty in the taxonomy of the url's i think. The problem i face that design often requires methods that are not easily identified by the resources/entities but by some function on them and thus a Url path with a verb instead of a noun makes more sense. For example in the typical example of a API with classes, students, grades etc what do you do if you need a method that returns a grade average? Or the best student? Also sometimes if you have extensive searching, filtering etc it just seems cleaner and simpler to have a simple URL and use a GET with body instead of the more correct RESTful taxonomy with URL and query parameters which becomes super long and harder to analyse in logging, dashboards etc.
@@markvanderwerf8592 /api/v1/classes/:classId/grades/average If you wanted to be ultra REST you could /api/v1/classes/:classId/grades?operation=average
@@markvanderwerf8592 That's what we've been calling accessing a "view" in RDBMS since the 1970's. As opposed to a "table" or "relation". And that's what I do for my "REST" APIs, "/rest/tablename" or "/view/viewname".
I know that TBL is credited for "inventing" HTML in 1989 but it's really just a specific simplified dialect of SGML (Standard Generalized Markup Language) from 1986 which, in turn, came out of IBM's GML (1960s) - which later evolved into XML. SGML was used in XICS (Xerox Integrated Composition System) (aka Xerox Compuset) which an electronic publishing system that combined the capabilities of HTML and CSS (with programmable tags too) before such things existed - back in the early/mid 1980s. For URLs and HyperText in general, take a look a Ted Nelson's "Project Xanadu" from back in the 1960s and 1970s. The WWW specification is, more or less, a watered-down version of that system delivered in a more pragmatic manner - Xanadu floundered around seeking perfection a little too long to be practical. Patents that were filed around the WWW technologies had prior art in the ideas of Xanadu and proof-of-concept implementations.
Indeed. Html is an instance of xml and xml was just an instance of sgml. SGML was VERY flexible. In fact probably too flexible. Don't like angle brackets? use parentheses, square brackets, percent signs, some obscure unicode character--just define it in the DTD (document type definition).
I happened to work with SGML before the web became a thing. And OMG what a beast it was. I was so happy that HTML was so much simpler. Writing a web page with SGML would have been like shooting an ant with a bazooka!
@@mikeschinkel That's the thing with a Generalized language. The idea is to put a set of rules around it that constrain it for a specific purpose, and then use that for getting the actual work done. HTML and, later, XHTML were those "languages".
@@mikeschinkel SGML wasn't designed for web pages. It was designed for things like putting digital versions of books in the library of congress in a way that you could still read them 50 or 100 years from now.
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)
"my backend, my frontend" that's the point. You own both. Consider an API made by a third party. Would you rather have an API where there is missing documentation, the documentation is outdated and incorrect, you have no idea what all endpoints are available or what they'll be named, and where the endpoints change regularly and break your application whenever they do or a HATEOAS API where you literally just need the root URL and you can click through links from there just like a website to discover whatever else you need to and navigate the whole API just like a website and where the owners update the links regularly but your client doesn't break because it's using the rels not the links which aren't changing....
@@neildutoit5177 Yeah most of the third party APIs I use in the system I manage, are full REST APIs with links to everything etc. It is such a blessing, I don't need to anything to figure out how their pagination works, I just follow the provided link. :)
"Delivers exactly what my frontend needs" - yes, that's REST and HATEOAS. well done. If the API *didn't* deliver what you need, and you had to get the rest from somewhere else, then your app is using out-of-band information and is not restful. What you like is good REST. What you dislike is bad rest.
@@NicholasShanks no - HATEOAS does not "deliver exactly what my frontend needs" - it delivers for instance, a list of urls, that my frontend then needs to request individually, to figure out what to display for each of them. Maybe I'd like to show a list of objects - but just show a list of names, and if the user decides to do something with any object: eg show or details, then I can fetch the entire object. I don't want to show the user a list or URLs, and I don't want to have to fetch every object individually, or have to fetch a huge structure with all the objects and all their details. I would like to design my JSON to include an id, and a name - for the list - and in some cases, maybe some other important property. I don't see how I can achieve that with HATEOAS, since I only get the urls of every object, and not eg the name as well ...
Even that's not accurate. ReST is an architectural constraint that you apply when designing something like the HTTP 1.1 spec, not when you're building an API that simply *uses* HTTP. Like, is it important for your organization that untrusted third parties are able to deploy independent endpoints to your domain that interoperate with other endpoints? No? Then why are we referring to the ReST paper, which cites [independent untrusted simultaneous deployment] as an underlying motivation? The whole thing is a red herring, just a convenient term to cite so that we could stop using SOAP, and to regain some of the caching techniques we gave up for no real reason in the early/mid aughts.
I love that you made this to clearly be one more part of the ongoing discussion and not "the answer". Good stuff, my dude. You have given me things to think about.
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".
@@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.
It was so fun thinking about this as the terminology since 1990 seemed to depend on the year or years a person would join API building. I can specifically see a progression of a APIs being defined differently by a software stack community/language depending on leaving a University in 2002 vs 2006 vs 2009 or vs 2016. Those are not specific dates for any particular technology, but if you started long ago writiing Java code, Spring, and sending SOAP objects-then saw a Zend 2 Framework in PHP providing HTTP methods to any front end such as Angular or an Android app-to then graduating now to build an API, it seems you would refer to the stack you may have used but in reality we can all understand what the other generation was doing. I appreciate that this brought up good memories of the years of learning APIs and how much some things change and other things stay similar.
This is the first video of yours that I've seen. Subscribed. I'm a long-time wanderer of the middle-country on your map,, usually running and often alone. I know what's over the hills and those guys usually have time and resources that I don't. The API I write is the API I need for right now, and nothing more. I may have time to iterate on it later, and I will. But my nearly three decades in this business have never result in any code designed for that time scale. Certainly some of it lasts a long time, but those external forces you mention eventually come along. I can't tell you what code I'll be writing a year from now, let alone many years from now. I haven't heard Fielding's name in a long time. I forgot about the origins of REST. Great video, and it went by very fast. Great use of time.
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.
This is one of the reasons I jumped on GraphQL, it properly defines the input and output formats, how to convey errors, none of that "which HTTP keyword should I use for what operation", etc... With REST, the only answer to questions about it is "you're doing it wrong".
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.
Generally, when I hear some labeling themselves as "architect" in IT, it is a pretty reliable indicator that they have no clue how things work in reality (but would like a big salary).
Very good video on REST including Web APIs. You have an art for communicating without getting into nonsensical(to non specialists) technicalities that bog down and characterize so called 'expert' programmers.
I love how your cat is screaming at you at 8:14 Other than that amazing video, is interesting to think about what sw companies call REST APIs to meaning basically what Swagger tries to do with OpenAPI
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.
Very insightful. I've never myself traversed the hills of hypermedia, but I've had my sights set on it with intrigue. It's good to know that I don't have to if I don't need it.
Nice and Clear. I was part of introducing REST in an embedded product, and I must admit that we never caught the Hypermedia thing. So - I guess we got it right ;-)
Thank you! This is the best explanation of what REST is and what it is not that I have seen! And a great catch up for me to the overall state of APIs currently!
Consider becoming a embedded systems developer. Start with building a kitchen timer which contains the micro-controller and it's own data. You get to learn both, software and hardware without the control of http: this and that which are sure to die. Your kitchen timer you build today, will be used and treasured by your son's and daughters for decades. If I were to start over I would have chosen this profession over software only.
You had me alllll the way to “language evolves to its usage”- ironic for programmers to say lol. Not to say you are wrong about any other part. Very educational and you got a subscriber.
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.
I tuned in knowing exactly what the debate/discussion would be. Fundamentally, on this one, it comes down to the fact that if I say "REST call" or "REST lookup" or "REST API" on a call, or an e-mail, every single person knows exactly what I mean by that with very little ambiguity.
Something I started playing around with in my project was using the schema to define dynamic structure. Say I have a bunch of different item types and the documents contain different aspects that aren't static, I used the schema to define the dynamic web content. Over time, that schema can change, new item types can be added. When handling these documents, a simple read of the document structure is used rather then applying the schema to it.
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 ;)
No, swagger is not rest. Every website you have ever used is rest. Rest is getting a web page, reading it, clicking a blue link, and getting another web page.
As someone new to concept of REST APIs, I grokked that the idea behind REST is to take advantage of HTTP URL structure and argument structure and leverage caching to the greatest extent possible to speed up and scale up your application. By encoding transfers in json, and by moving all the cacheable-response endpoints to the url file path endpoints (only : no arguments), and by designing a hierarchical RPC function call and versioning naming scheme, you take maximum advantage of HTTP and Internet infrastructure to make a performant application.
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.
This was the way of web programming 20 years ago with "Web 2.0"... Funny that (probably young) people think that this is something new in 2024 and even a good choice. There's a reason why development left that muddy trail many years ago.
@@-Jakob- literally nobody in the htmx community thinks htmx invented sending HTML. Just because people used to do things a certain way and they don't anymore doesn't mean that way is objectively, irredeemably bad. "There's a reason why development left that muddy trail many years ago." Yes, because HTML didn't have the tools needed for highly interactive interfaces, and when implementing them via JavaScript, it seemed more logical to imitate native app toolkits rather than build something that works with the Web model.
I consider it a good choice sometimes because backend technology has come a long way from back then. This makes this Web 2.0ish approach actually feasible for some apps (not all of course, but no technology is suited for all apps)
The other thing about openapi that goes under the radar is that since it's a structured document you can use it validate test results, make sure responses match schemas, and all sorts of other dynamic testing. It has saved me so many hours of work by not having to write and maintain every single test. Nevermind all the codegen opportunities it gives. OpenAPI was game changing on my end.
Solid vid. I’ve been long on team REST is what 99% of us have been doing, which is just exposing (with some consideration of course) HTML endpoints on the web. If there was a payoff for doing REST “correctly” we’d have seen some influential industry examples by now.
In my opinion you and many others are building 404 servers. Works today, but possibly not tomorrow. AKA throw-a-way software. The large providers of those web based apis. Do not really want you to have the data, and if they do they will give you some crappy api and partial access to the gold nuggets. Don't get me wrong the http stuff changed the world, it could just have been so much better. In closing: Today there might be an incredible document, tomorrow it could be gone for ever. The internet looses insane amount of great data because of the system they used. How many "Mark Twain" like books are gone?
The core of REST became wildly successful, and left behind "correctness". CRUD APIs, separate the RPC from any object model, and the best part: use the ports everyone already had open on their firewalls. RESTful was the big win.
Oh god...soooo much XML. The horror! Pages and pages and pages of it. The XML just used to keep on coming until it spilled out of the computer and you were up to your knees in it. Dreadful protocol.
“Hypermedia as the engine of application state.” HATEOAS. I think it is still viable for certain cases, even if Dylan disagrees. I have not finished the video, yet.
I think this is close to the right approach. Let the pedants endlessly discuss how many blahblahblahs can dance on the head of a pin. Meanwhile, I got stuff to do. This video was super annoying & I wish it said that in the title.
I’ve been saying this for years. There’s always a cool kid on the block that everyone should use. I see so many resources online that muddy the waters when people with small experience try and offer training to others online. REST was definitely one of these and probably peaked in popularity ten years ago. I’ve integrated with many 3rd party ‘REST’ apis over the years and none of them were true REST. Some closer than others. The better ones were the consistent ones. Others were an absolute mess that caused issues months down the line when it started giving totally unexpected response with a totally different error format. The worst had 1 page documentation with no description of fields or what type they were, just the names which weren’t that descriptive.
As someone who works specifically in enterprise integration - REST in general was a massive retrograde step from SOAP, with Swagger - sorry - OpenAPI moving to replace WSDL where it is actually used. What we have seen in practice was vendors building their single page web apps with JAX-RPC type tech and just making the underlying APIs public with little documentation or error handling. The difference of meaning between PUT/PATCH/DELEtE varies wildly from implementation to implementation and error handling has become impossible with 404 (say) meaning the record hasn’t been found or the API isn’t running. Presenting interfaces for external integration is.very much an afterthought and almost always poorly implemented. I would argue even the concept of REST as representation state transfer breaks encapsulation and forces external interfaces to understand the lifecycle of objects in a third part system - but given the real world implementation we have seen - that dream I never materialised anyway, A good API should encapsulate the functionality of the target system, allow efficient bulk operations and be explicit about errors so they can be handled properly by the calling system. Vendors rarely understand this.
What you're complaining about isn't REST, it's low-effort APIs. And low-effort REST APIs are definitely better than the alternative, because they _exist._ The alternative wasn't some glorious self-describing framework, the alternative was an abandoned project when funding ran out with nothing to show.
As a fellow enterprise integration specialist, let me say that I share your pain. When people inexplicably started to use REST APIs for external integration (or more frequently something that definitely wasn't a REST API but which they called one regardless), integration development slowed down to a crawl. It took 10 minutes to make a 100% correct and fully functional client for any SOAP service, while making a client for a REST API could take weeks.
Thanks for this! Really interesting and succinct history. My company is in the process of rolling out some new internal dev standards. It's fascinating to me how rarely people understand the original intent of certain patterns and technologies. We use a kind of hacky RPC design that people still call REST 😬🤷🏽♂️
About five years ago at work I had to work on a project that was integrating with a partner that used HATEOS links and it was a pain in the ass to deal with. In my 10 year career (at that point) I had never encountered an API that was designed that way and I haven't again since then.
Great content! I 'm still doing SOAP as it is a kind of industry standard over here in germany for insurance data. Beside that I try to explain my customers, that rest needs hypermedia in a format like HAL (most used by me) and HATEOAS. Most of the teams I 'm working with don 't even know HAL or HATEOAS in these days. Ofcourse hypermedia is an additional expense on REST APIs. But the benefit out of that is worth it.
the thing is that, in order to have REST you need to use HTML not JSON, precisely because HTML is already a Hypermedia standard and is the most adopted, JSON as its name imply is a JavaScript Object Notation, which you can use to define custom hypermedia but is not a hypermedia standard, that is why all these attempts like HAL have failed because they try to reinvent the wheel with squares. And the browser is already the hypermedia client we need, not some JS library.
Yes and no. The HTML spec is missing some functionality to be more fully useable. For the time being we need "some" JS library, HTMX, to extend that. Until the ideas are possibly taken over into HTML proper.
It reminds me of the legacy of the term « object oriented », coined in Simula (but which was really just message passing), but now the term « object oriented » means something completely different
Hype happens when you give only the pros and misrepresent (or don't represent) the cons and therefore misrepresent the impact. This is especially true if you misrepresent the cost of implementation. Hype can also be used as a tool to replace an even worse system - just realize that your new system isn't nearly as good as you think it is especially 5 years later. Someone will use hype eventually to upgrade your system which is a good thing because it means that your product is not dead.
No it does not need more science in the industry. I often find that Phd students do the worst at interviews because they don't know how to program and only have domain specific knowledge that is not applicable to the industry. A rockstar developer is a developer that can learn on there own and never stops.
@@AbNomal621 Exactly, dynamic user interfaces AT RUNTIME is not a problem professional developers experience. It is not even that good for low code/no code.
I agree with you 100% regarding the terminology. Unfortunately, the PHBs of the world love their buzzwords, and if the proposal does not include those buzzwords, it does not get accepted. Thus, one is forced to refer to RESTful APIs, when you bloody well know that they are not going to be since there will be no hypermedia references, they are at best just plain HTTP/S APIs, and swagger does a brilliant job expressing the methods and parameter models.
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?
@@Dennis-vh8tz The problem is complexity. Since JSON and "restful" APIs are in general are awful, awful abstractions they require HUGE amounts of tooling to even be kind of usable. JSON has no constraints, its the wild west. If you try to use it bare bones, your application will be fragile and filled to the brim with bugs. And so we create JSON schema and OpenAPI. That covers 60% of what you need, but your complexity has shot up. And for each percent more of constraints you require, the more of a Frankenstein you build. Suddenly 100 libraries to send customer data doesn't seem so crazy. Sure, your developers are "familiar" with it - but not really, because there's no human on Earth who can truly understand it. How does your application work? Who knows, its 95% library code. Or... you can choose standards which better fit what you're building, and reduce the noise.
We have a "REST API" but for some reason we change the API with every release. And sometimes we bump the version of single endpoints, not the whole API we don't use minor version. The versions before are immediately deprecated. And we will delete them when we sense they're no longer used. They tend to just return some JSON containing the data for each use case, no general resources or anything. The user's direct use cases defines what our api looks like. Totally fully REST.
Dylan, I've loved watching some of your tasks in the past, especially on "Enterprise" software and "TDD, where did we go wrong?". However in this case I'm not sure I agree with your conclusion or closing thoughts here. After having read the book on Hypermedia systems and learning htmx (I'm old enough to have lived some of the earlier days of the web), I think Hypermedia Driven Applications and Hypermedia in general still have a place.
In 2002, I was forced to integrate our enterprise system with SAP and of course they used SOAP. What a terrible experience. I never used it again unless it’s absolutely necessary. Since then I’ve always written dozens of web APIs with thousands of endpoints like Open API but because it was simple and it worked.
Why try to over define what it means? It’s a clean and simple way to get/set/delete resources from a server, way more simple and with less overhead than soap, which is a bloated piece of junk where the syntax takes up more space than the actual data. I actually prefer simple Telnet API , that way you can reduce overhead even further.
Proud to stand in the corner of using REST properly on the handful of projects Ive built for companies. Unfortunately they all suffered the same fate and now either dont exist or have been swolled up by THETHING
What was/is important about REST and REST operations (which can be used by not REST) is that it gives/gave a common language to use on APIs which everyone knew. That was huge it accelerated development, increased compatibility, and increased transferable skills.
That's funny, my experience has been the exact opposite. Having to consume external REST APIs slows down development tremendously. There is no "common language", every API is unique and structured differently. There is less compatibility because nothing is officially standardized, and the "skills" you acquire from writing a client for one API have very little application in writing a client for another. You're essentially starting from scratch every time.
@@Wishbone1977 that's why apis need to be documented. Every API whether REST or internal to the program must have documentation. Automated documentation is a thing.
@@wayhip Automated documentation _is_ indeed a thing. Now ask me how many of the "REST APIs" I had to consume 10 years ago used it. Also, tooling is _important_ for productivity. And 10 years ago, there wasn't any proper tooling to help with making clients for REST APIs. Given the lack of standardization, making proper tooling was more or less impossible. You say they were the best alternative at the time? For _external_ integration? No, they were not. Not by a long shot.
@@Wishbone1977 Not creating proper documentation is a programmer issue not an API issue. I did over 20 years in tech. Including programming (about half of it), DBA and sysadmin work, and QA. While talking to friends of mine with similar backgrounds we concluded that your typical programmer has the self discipline of incontinent baboons. Software Engineer my 4$$. Granted they often labor in bad work places but they shipped it without completing it. Their tech leads and managers let them get away with it.
I was aware that it existed. I just never have time to investigate adding those links. If I have a an api endpoint for customer information /customer I will either have /customer/custid/invoices or /invoices/custid. Instead of parsing out the what can be done with the links, where all the heavy lifting has been done on the server side. The application code in browser implements the business logic, requests resources without hyperlinks and makes decisions about how to present the UI.
@@neildutoit5177 It is easy enough. Most of us start with just needing to get data from the backend to the font end and visa versa. If you can't do that all else is academic. Tutorials and libraries are focused on that. Everything related to hypermedia besides pagination is not needed. I need to get my app out the door. I know how I am coding my front end. Taking the time to duplicate my front end UI logic in hypermedia is counter productive to hitting deadlines. You can argue that is the case because the programmer does not understand Hypermedia. However, the reality is that 90%+ of REST API's are about shuttling data and not about using hypermedia properly.
Because nobody really cares to painfully navigate some "links" and guess their meanings when they can get a list of the actual, specified API endpoints for whatever they need to access anyhow.
@@clray123the point is you don't guess. It is defined. Rest is the difference between and your browser "knowing" that all stylesheets live at /style.css so the web page does not need to say. /favicon.ico is NOT rest, rel=icon *is*
Agree on most but GraphQL. It is an anti pattern, the same thing was done in the 90s when people were sending SQLs from application directly to sql server. Sure now you filter and secure access to data with graphql, but APIs should be explicit, 1:1 data/operation to use case.
I still hate to co-opting of the HTTP error codes to report application errors. I know that in the OSI Model the HTTP layer is the application layer, but in practice we have built our own thing, that runs on top of HTTP, and so for most of this stuff if we are honest with ourselves HTTP is the transport layer now, and our specific messages that just happen to be exchanged via HTTP are the actual application layer. So no, I won't be putting my application errors into the transport. Its also bad coupling, What happens if you want to transmit message by something other than HTTP?
The usual compromise is to only indicate the category (success/no-success) and blame (client-problem/server-problem) through the HTTP code and do the rest with your application-specific error messages. Which you will need anyway to provide sensible aids for debugging.
I'll stop calling it "REST" when we stop calling whatever we're doing "Agile".
I am so glad I left mega corp when Agile came along and went to a small startup. Agile was the death of software development.
Bruh just because we're using JIRA doesn't make it Agile
@@KeithThompsonFAMU97 truths, its just Kanban, nuthing else o:
😂
😅😅😅
As a card carrying restafarian and an editor of the OpenAPI specification, I want to say thank you for your service. Clear, concise unbiased explanations are something we can never have enough of.
Been a developer for almost a decade and now I realize that I’ve never ever written a proper REST API. Thanks for the correction 😂
95% of devs from the last 15 years have not either
I've accidentally written a few.
I have been making the correction to say RESTlike API for years. Words have meaning and I want to be precise with my speech.
@@MrJoefinisher Or RESTful. But yeah, Dylan's right. We've moved on from the REST idea as originally designed, but that's totally okay, because without REST, I don't think Swagger/Open API could ever have existed.
Honestly, if your API has anything like a login, it's not a REST API. The whole point of REST is to have efficient intermediate caching. CDNs use REST. Nobody else does.
I totally expected something else from the title, but I got a video absolutely worth the time. Great summary of the status quo. And yes, people say "REST" when essentially they mean "I'm calling some endpoint that roughly follows the Swagger guidelines and I'm getting back some JSON".
Maybe. Or they mean "Representation State Transfer". The server maintains a global state and clients request representations of that state or update small portions of that state represented by a URL. State need not be a directory structure of hyper media. State can be a map of the Earth or a web shop or music catalog. The client cannot know all server state and the server need not know all details of client state.
I do agree that JSON somehow implies ReST when they have nothing to do with each other, no more than JPEG is HTTP
@@familyshare3724 Yes, the two things are completely unrelated but have been conflated because both were designed to make communication between a website and its own backend easier, hence the two were usually used together. This has intertwined the two in most people's minds.
In my 25 years of experience I've yet to meet a REST purist who was good at anything but making ppt slides.
6:36 missed opportunity... "here in the middle we've got "The Rest"😂
also a missed "rest assured" at the start
the rest of the talk was pretty good, though.
"the restful fields"
I always like to see a dev who's not dogmatic. It's an engineer's approach, and I respect it a lot.
Thumbs up for the callout against returning an error in a 200 OK.
I think that's stylistic. To me, 200 OK means "the program didn't crash." e.g. it ran successfully but "you asked for a customer without supplying the customer ID" or whatever is a "supported" error condition -- the page will run (200 OK) but if you're going to get what you came here for, you're going to have to do something different. But to each their own.
@@kevinrusch3627We already have error codes for when servers crash (or encounter other issues), those being Internal Server Errors.
Servers should return error codes like 500 when an endpoint, be it valid or invalid, results in the server experiencing an unexpected condition. Returning code 200 (OK) is confusing (and dare I say, objectively wrong) for an unsuccessful call because it indicates "What you have asked me to do was valid and I have done it." to the caller.
@@kevinrusch3627idk about style but I'd say 400 bad request would be way more fitting
@@kevinrusch3627the frontend should be checking those things. So if that reaches the backend, it's a problem with the software (=frontend + backend) as a whole, so deserves an error code.
4xx codes are used for frontend mistakes, 5xx for backend mistakes.
Crashes in the backend will always return a 5xx code.
So, what a 404 means? You have a wrong url or the operation didn’t find any result?
I think is more logical separate the message from the messenger.
You have successfully managed to explain in 10 minutes what others didn’t in hours of courses or many in books. Condensed, useful information 👏
My favorite part is that you ended the video reminding us to look after each other.
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.
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.
yeah, as a learner, i easily find the theoretical ways stuff is supposed to work. what's scarcer is how stuff works in the real world
Writing software is easier today, good on one hand for the short limited life span and bad in many ways. Example: If you write a piece of software today and it consumes a google api using some api link. I will guarantee your software will die the day that url disappears. Explain that to your boss 3 years from now when your application fails to run. I sometimes wish I had followed embedded systems engineering. At least if I engineer a toaster, that toaster would run until electricity flowed. These days, your toaster could stop making toast because googles toaster api was retired. This means, google owns your software not you. I chose not to embrace the puny weak hacked stuff. As you will end up with a 404 not found application.
"Representation State Transfer". The server maintains a global state and clients update or request minimal state by a URL. State need not be a directory structure of hyper media. State can be a map of the Earth or a web shop or music catalog. The client cannot know all server state and the server need not know all details of client state. HTTP error codes are useful in protocols generally: 2xx OK, 3xx go away, 4xx bad request, 500 bad server
REST makes everything simpler and predictable, much easier to develop and test. In theory a minimal request returns a minimal response without sharing each other's State. Call and forget. Any session token and state lookup always complicates things and should be kept to a minimum. "Do you have any widgets and how much do they cost?" Just answer the question rather than: who are you, what else are you looking for, why are you asking, have you been here before, how much can you afford, do you have a job, maybe you like turtles?
"difference between standards" between Rest and say SOAP? No. ReST is the only game in town, not just web pages over HTTP. Even RCP can be ReST. Are you sharing and maintaining (minimal) state or not?
Suppose you develop a game. You might think the server should maintain all state and clients just ask for state. Maybe, but should the server draw the pixels on each screen, too? The client asks "how much money do I have?" but not "I have $1 million". The client says "I move forward" not "I am in the castle" nor "this is my entire reality" nor ask "what is my entire reality?".
Rep State Transfer:
C: I move forward.
S: you cannot.
C: I move left.
S: You see a chair.
C: I sit in chair.
S: Ok.
C: I kick chair.
S: you have 50% health, the chair is at x, y, and you see a gold coin
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.
I feel is all sbout selling cloud...
Need a more safe model to sell , model timeshare cant works.
Hence refactoring bybthe goodbold category theory with monads andvlogic topology...
Hence no acid crud butbbase crud😊
Many 'Restful' APIs have difficulty in the taxonomy of the url's i think. The problem i face that design often requires methods that are not easily identified by the resources/entities but by some function on them and thus a Url path with a verb instead of a noun makes more sense.
For example in the typical example of a API with classes, students, grades etc what do you do if you need a method that returns a grade average? Or the best student?
Also sometimes if you have extensive searching, filtering etc it just seems cleaner and simpler to have a simple URL and use a GET with body instead of the more correct RESTful taxonomy with URL and query parameters which becomes super long and harder to analyse in logging, dashboards etc.
@@markvanderwerf8592 /api/v1/classes/:classId/grades/average
If you wanted to be ultra REST you could /api/v1/classes/:classId/grades?operation=average
@@markvanderwerf8592 That's what we've been calling accessing a "view" in RDBMS since the 1970's. As opposed to a "table" or "relation". And that's what I do for my "REST" APIs, "/rest/tablename" or "/view/viewname".
Rest has nothing to do with the content of URLs. Absolutely nothing. A restful api can use meaningless gibberish as its uris.
I know that TBL is credited for "inventing" HTML in 1989 but it's really just a specific simplified dialect of SGML (Standard Generalized Markup Language) from 1986 which, in turn, came out of IBM's GML (1960s) - which later evolved into XML. SGML was used in XICS (Xerox Integrated Composition System) (aka Xerox Compuset) which an electronic publishing system that combined the capabilities of HTML and CSS (with programmable tags too) before such things existed - back in the early/mid 1980s.
For URLs and HyperText in general, take a look a Ted Nelson's "Project Xanadu" from back in the 1960s and 1970s. The WWW specification is, more or less, a watered-down version of that system delivered in a more pragmatic manner - Xanadu floundered around seeking perfection a little too long to be practical. Patents that were filed around the WWW technologies had prior art in the ideas of Xanadu and proof-of-concept implementations.
Indeed. Html is an instance of xml and xml was just an instance of sgml. SGML was VERY flexible. In fact probably too flexible. Don't like angle brackets? use parentheses, square brackets, percent signs, some obscure unicode character--just define it in the DTD (document type definition).
I happened to work with SGML before the web became a thing. And OMG what a beast it was. I was so happy that HTML was so much simpler. Writing a web page with SGML would have been like shooting an ant with a bazooka!
@@mikeschinkel That's the thing with a Generalized language. The idea is to put a set of rules around it that constrain it for a specific purpose, and then use that for getting the actual work done. HTML and, later, XHTML were those "languages".
You don't have enough thumbs ups on this comment.
@@mikeschinkel SGML wasn't designed for web pages. It was designed for things like putting digital versions of books in the library of congress in a way that you could still read them 50 or 100 years from now.
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)
"my backend, my frontend" that's the point. You own both.
Consider an API made by a third party. Would you rather have an API where there is missing documentation, the documentation is outdated and incorrect, you have no idea what all endpoints are available or what they'll be named, and where the endpoints change regularly and break your application whenever they do or
a HATEOAS API where you literally just need the root URL and you can click through links from there just like a website to discover whatever else you need to and navigate the whole API just like a website and where the owners update the links regularly but your client doesn't break because it's using the rels not the links which aren't changing....
@@neildutoit5177 Yeah most of the third party APIs I use in the system I manage, are full REST APIs with links to everything etc. It is such a blessing, I don't need to anything to figure out how their pagination works, I just follow the provided link. :)
"Delivers exactly what my frontend needs" - yes, that's REST and HATEOAS. well done. If the API *didn't* deliver what you need, and you had to get the rest from somewhere else, then your app is using out-of-band information and is not restful.
What you like is good REST. What you dislike is bad rest.
@@NicholasShanks no - HATEOAS does not "deliver exactly what my frontend needs" - it delivers for instance, a list of urls, that my frontend then needs to request individually, to figure out what to display for each of them. Maybe I'd like to show a list of objects - but just show a list of names, and if the user decides to do something with any object: eg show or details, then I can fetch the entire object. I don't want to show the user a list or URLs, and I don't want to have to fetch every object individually, or have to fetch a huge structure with all the objects and all their details. I would like to design my JSON to include an id, and a name - for the list - and in some cases, maybe some other important property.
I don't see how I can achieve that with HATEOAS, since I only get the urls of every object, and not eg the name as well ...
Love that your TH-cam videos are as well researched and full of background as your talks, another awesome video Dylan
This, 100%
That mismatch is the reason why most people call it RESTful today.
I always call it RESTish or REST-like
@@andrewmazar4921 How about NAP (Network API Pattern). Not quite a full REST but reasonably close.
@@ulteriormotif I could use a nap alright
yeah. Most people actually don’t seem to know much about what the original REST style was and generally just think “json over http”.
Even that's not accurate. ReST is an architectural constraint that you apply when designing something like the HTTP 1.1 spec, not when you're building an API that simply *uses* HTTP. Like, is it important for your organization that untrusted third parties are able to deploy independent endpoints to your domain that interoperate with other endpoints? No? Then why are we referring to the ReST paper, which cites [independent untrusted simultaneous deployment] as an underlying motivation?
The whole thing is a red herring, just a convenient term to cite so that we could stop using SOAP, and to regain some of the caching techniques we gave up for no real reason in the early/mid aughts.
I love that you made this to clearly be one more part of the ongoing discussion and not "the answer". Good stuff, my dude. You have given me things to think about.
What a wonderful gem of a channel I’ve just discovered :)
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
It was so fun thinking about this as the terminology since 1990 seemed to depend on the year or years a person would join API building. I can specifically see a progression of a APIs being defined differently by a software stack community/language depending on leaving a University in 2002 vs 2006 vs 2009 or vs 2016. Those are not specific dates for any particular technology, but if you started long ago writiing Java code, Spring, and sending SOAP objects-then saw a Zend 2 Framework in PHP providing HTTP methods to any front end such as Angular or an Android app-to then graduating now to build an API, it seems you would refer to the stack you may have used but in reality we can all understand what the other generation was doing. I appreciate that this brought up good memories of the years of learning APIs and how much some things change and other things stay similar.
This is the first video of yours that I've seen. Subscribed. I'm a long-time wanderer of the middle-country on your map,, usually running and often alone. I know what's over the hills and those guys usually have time and resources that I don't. The API I write is the API I need for right now, and nothing more. I may have time to iterate on it later, and I will. But my nearly three decades in this business have never result in any code designed for that time scale. Certainly some of it lasts a long time, but those external forces you mention eventually come along. I can't tell you what code I'll be writing a year from now, let alone many years from now. I haven't heard Fielding's name in a long time. I forgot about the origins of REST. Great video, and it went by very fast. Great use of time.
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.
Don't get hung up on the duplication (or normalization) part. Full fideltiy apis often have problems even at medium scale.
This is one of the reasons I jumped on GraphQL, it properly defines the input and output formats, how to convey errors, none of that "which HTTP keyword should I use for what operation", etc... With REST, the only answer to questions about it is "you're doing it wrong".
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.
Generally, when I hear some labeling themselves as "architect" in IT, it is a pretty reliable indicator that they have no clue how things work in reality (but would like a big salary).
Very good video on REST including Web APIs. You have an art for communicating without getting into nonsensical(to non specialists) technicalities that bog down and characterize so called 'expert' programmers.
I love how your cat is screaming at you at 8:14
Other than that amazing video, is interesting to think about what sw companies call REST APIs to meaning basically what Swagger tries to do with OpenAPI
+1 for confirming I wasn't hallucinating the cat
It's still screaming at the end of the video ( 10:34 ) .. clearly it has a different opinion on what constitutes a REST API.
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.
citation needed is lowkey the funniest thing I've seen in a hot minute
Very insightful. I've never myself traversed the hills of hypermedia, but I've had my sights set on it with intrigue. It's good to know that I don't have to if I don't need it.
this was really well explained and you should be proud of the work you put into this :)
Nice and Clear. I was part of introducing REST in an embedded product, and I must admit that we never caught the Hypermedia thing. So - I guess we got it right ;-)
Thank you! This is the best explanation of what REST is and what it is not that I have seen! And a great catch up for me to the overall state of APIs currently!
I don't know very much about REST and I've been trying to learn and this is the most helpful thing I've encountered so far.
Consider becoming a embedded systems developer. Start with building a kitchen timer which contains the micro-controller and it's own data. You get to learn both, software and hardware without the control of http: this and that which are sure to die. Your kitchen timer you build today, will be used and treasured by your son's and daughters for decades. If I were to start over I would have chosen this profession over software only.
You had me alllll the way to “language evolves to its usage”- ironic for programmers to say lol. Not to say you are wrong about any other part. Very educational and you got a subscriber.
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.
I want to build a TH-cam controller from an old TV tuner now.. just so I can tune in to this channel again.
Glad this came up in my recommended feed. I will be tuning in again.
I tuned in knowing exactly what the debate/discussion would be. Fundamentally, on this one, it comes down to the fact that if I say "REST call" or "REST lookup" or "REST API" on a call, or an e-mail, every single person knows exactly what I mean by that with very little ambiguity.
Something I started playing around with in my project was using the schema to define dynamic structure. Say I have a bunch of different item types and the documents contain different aspects that aren't static, I used the schema to define the dynamic web content. Over time, that schema can change, new item types can be added. When handling these documents, a simple read of the document structure is used rather then applying the schema to it.
I've always watched your NDC conferences but didn't realise you had your own YT channel until now! Keep up the awesome content 🤍
Huh. Had no idea you had a youtube channel. Thanks for the information and inspiration over the years, my guy.
Your ending about language evolution was perfectly illustrated
I had no idea you had a channel!!
I love your presentations! some of my faves
great video. subscribed
Brilliantly explained at great fast pace! Fantastic!
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 ;)
Finally, I understood what REST is. Your Swagger example was on point. Thank you!
No, swagger is not rest. Every website you have ever used is rest. Rest is getting a web page, reading it, clicking a blue link, and getting another web page.
Loved this breakdown, subbed!
Missed opportunity here not titling the video “Turns out REST APIs weren't the answer (and that's 200)”
As someone new to concept of REST APIs, I grokked that the idea behind REST is to take advantage of HTTP URL structure and argument structure and leverage caching to the greatest extent possible to speed up and scale up your application. By encoding transfers in json, and by moving all the cacheable-response endpoints to the url file path endpoints (only : no arguments), and by designing a hierarchical RPC function call and versioning naming scheme, you take maximum advantage of HTTP and Internet infrastructure to make a performant application.
Amen to this. I was involved in a system where the management decided it had to be REST. It was a real-time control system. What a bad fit.
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!!!
This was the way of web programming 20 years ago with "Web 2.0"... Funny that (probably young) people think that this is something new in 2024 and even a good choice. There's a reason why development left that muddy trail many years ago.
@@-Jakob- literally nobody in the htmx community thinks htmx invented sending HTML. Just because people used to do things a certain way and they don't anymore doesn't mean that way is objectively, irredeemably bad.
"There's a reason why development left that muddy trail many years ago." Yes, because HTML didn't have the tools needed for highly interactive interfaces, and when implementing them via JavaScript, it seemed more logical to imitate native app toolkits rather than build something that works with the Web model.
Yay s and cross site scripting
I consider it a good choice sometimes because backend technology has come a long way from back then. This makes this Web 2.0ish approach actually feasible for some apps (not all of course, but no technology is suited for all apps)
The other thing about openapi that goes under the radar is that since it's a structured document you can use it validate test results, make sure responses match schemas, and all sorts of other dynamic testing. It has saved me so many hours of work by not having to write and maintain every single test. Nevermind all the codegen opportunities it gives. OpenAPI was game changing on my end.
Bravo! Excellent video! you take the words out of my mind and nailed them to the youtube post.
Solid vid. I’ve been long on team REST is what 99% of us have been doing, which is just exposing (with some consideration of course) HTML endpoints on the web.
If there was a payoff for doing REST “correctly” we’d have seen some influential industry examples by now.
In my opinion you and many others are building 404 servers. Works today, but possibly not tomorrow. AKA throw-a-way software. The large providers of those web based apis. Do not really want you to have the data, and if they do they will give you some crappy api and partial access to the gold nuggets. Don't get me wrong the http stuff changed the world, it could just have been so much better. In closing: Today there might be an incredible document, tomorrow it could be gone for ever. The internet looses insane amount of great data because of the system they used. How many "Mark Twain" like books are gone?
The core of REST became wildly successful, and left behind "correctness". CRUD APIs, separate the RPC from any object model, and the best part: use the ports everyone already had open on their firewalls. RESTful was the big win.
We have: every web browser is a successful web client and every web server is a successful web server.
Somehow REST reminds me of Humpty Dumpty:
"When I use a word,” Humpty Dumpty lectures Alice, “it means exactly what I say it means and nothing more.”
SOAP/WDSL haunts my nightmares!! 😢
Oh god...soooo much XML. The horror! Pages and pages and pages of it. The XML just used to keep on coming until it spilled out of the computer and you were up to your knees in it. Dreadful protocol.
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 think at the very least it means using HTTP. The rest is negotiable.
“Hypermedia as the engine of application state.” HATEOAS.
I think it is still viable for certain cases, even if Dylan disagrees. I have not finished the video, yet.
To me if OpenAI can create client library for you and it’s useable then you’re a Rest API.
I think this is close to the right approach. Let the pedants endlessly discuss how many blahblahblahs can dance on the head of a pin. Meanwhile, I got stuff to do. This video was super annoying & I wish it said that in the title.
@@OMGclueless which, ironically, isn't even a requirement in the original definition
I’ve been saying this for years. There’s always a cool kid on the block that everyone should use. I see so many resources online that muddy the waters when people with small experience try and offer training to others online. REST was definitely one of these and probably peaked in popularity ten years ago. I’ve integrated with many 3rd party ‘REST’ apis over the years and none of them were true REST. Some closer than others. The better ones were the consistent ones. Others were an absolute mess that caused issues months down the line when it started giving totally unexpected response with a totally different error format. The worst had 1 page documentation with no description of fields or what type they were, just the names which weren’t that descriptive.
Dialed to 2.4 GHz just to tune in and say: "You give REST a bad name!"
Will see myself out now...
...GREAT VIDeo by the way... :)
As someone who works specifically in enterprise integration - REST in general was a massive retrograde step from SOAP, with Swagger - sorry - OpenAPI moving to replace WSDL where it is actually used. What we have seen in practice was vendors building their single page web apps with JAX-RPC type tech and just making the underlying APIs public with little documentation or error handling. The difference of meaning between PUT/PATCH/DELEtE varies wildly from implementation to implementation and error handling has become impossible with 404 (say) meaning the record hasn’t been found or the API isn’t running. Presenting interfaces for external integration is.very much an afterthought and almost always poorly implemented. I would argue even the concept of REST as representation state transfer breaks encapsulation and forces external interfaces to understand the lifecycle of objects in a third part system - but given the real world implementation we have seen - that dream I never materialised anyway, A good API should encapsulate the functionality of the target system, allow efficient bulk operations and be explicit about errors so they can be handled properly by the calling system. Vendors rarely understand this.
What you're complaining about isn't REST, it's low-effort APIs. And low-effort REST APIs are definitely better than the alternative, because they _exist._ The alternative wasn't some glorious self-describing framework, the alternative was an abandoned project when funding ran out with nothing to show.
As a fellow enterprise integration specialist, let me say that I share your pain. When people inexplicably started to use REST APIs for external integration (or more frequently something that definitely wasn't a REST API but which they called one regardless), integration development slowed down to a crawl. It took 10 minutes to make a 100% correct and fully functional client for any SOAP service, while making a client for a REST API could take weeks.
They claim that he invented HTML should always have an asterisk next to it, pointing out that really HTML was just a subset of SGML.
Dylan, you didn't mention OData; have you used it? I spent a lot of effort working with it on a project and there is some VERY good but also some bad.
Thanks for this! Really interesting and succinct history. My company is in the process of rolling out some new internal dev standards. It's fascinating to me how rarely people understand the original intent of certain patterns and technologies. We use a kind of hacky RPC design that people still call REST 😬🤷🏽♂️
I will put this video in my list of "Informatics Philosophies"
Finally some sense! Great info thanks for sharing and providing light in this APIs Jungle
About five years ago at work I had to work on a project that was integrating with a partner that used HATEOS links and it was a pain in the ass to deal with. In my 10 year career (at that point) I had never encountered an API that was designed that way and I haven't again since then.
Great content! I 'm still doing SOAP as it is a kind of industry standard over here in germany for insurance data. Beside that I try to explain my customers, that rest needs hypermedia in a format like HAL (most used by me) and HATEOAS. Most of the teams I 'm working with don 't even know HAL or HATEOAS in these days. Ofcourse hypermedia is an additional expense on REST APIs. But the benefit out of that is worth it.
randomly stumbled across this video, but Dylan seems cool. I will definitely watch more videos of this channel.
HTTP...I saw what you said there. The overdub was close to perfect ;)
the thing is that, in order to have REST you need to use HTML not JSON, precisely because HTML is already a Hypermedia standard and is the most adopted, JSON as its name imply is a JavaScript Object Notation, which you can use to define custom hypermedia but is not a hypermedia standard, that is why all these attempts like HAL have failed because they try to reinvent the wheel with squares. And the browser is already the hypermedia client we need, not some JS library.
Yes and no. The HTML spec is missing some functionality to be more fully useable. For the time being we need "some" JS library, HTMX, to extend that. Until the ideas are possibly taken over into HTML proper.
JSON (JavaScript Object Notation) like HTTP is NOT what its name implies. It became its own thing via RFC almost a decade ago.
It reminds me of the legacy of the term « object oriented », coined in Simula (but which was really just message passing), but now the term « object oriented » means something completely different
Computer science needs more science and less hype.
Fortunately, I completed my Computer Science Degree before the hype.
That was before
Hype happens when you give only the pros and misrepresent (or don't represent) the cons and therefore misrepresent the impact. This is especially true if you misrepresent the cost of implementation. Hype can also be used as a tool to replace an even worse system - just realize that your new system isn't nearly as good as you think it is especially 5 years later. Someone will use hype eventually to upgrade your system which is a good thing because it means that your product is not dead.
No it does not need more science in the industry. I often find that Phd students do the worst at interviews because they don't know how to program and only have domain specific knowledge that is not applicable to the industry. A rockstar developer is a developer that can learn on there own and never stops.
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.
@@AbNomal621 Exactly, dynamic user interfaces AT RUNTIME is not a problem professional developers experience. It is not even that good for low code/no code.
I agree with you 100% regarding the terminology. Unfortunately, the PHBs of the world love their buzzwords, and if the proposal does not include those buzzwords, it does not get accepted. Thus, one is forced to refer to RESTful APIs, when you bloody well know that they are not going to be since there will be no hypermedia references, they are at best just plain HTTP/S APIs, and swagger does a brilliant job expressing the methods and parameter models.
Just a note of appreciation for "The Consolidated Cheese and Diesel Corporation" at 03:56 🤣
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?
@@Dennis-vh8tz The problem is complexity. Since JSON and "restful" APIs are in general are awful, awful abstractions they require HUGE amounts of tooling to even be kind of usable. JSON has no constraints, its the wild west. If you try to use it bare bones, your application will be fragile and filled to the brim with bugs. And so we create JSON schema and OpenAPI. That covers 60% of what you need, but your complexity has shot up. And for each percent more of constraints you require, the more of a Frankenstein you build. Suddenly 100 libraries to send customer data doesn't seem so crazy. Sure, your developers are "familiar" with it - but not really, because there's no human on Earth who can truly understand it. How does your application work? Who knows, its 95% library code. Or... you can choose standards which better fit what you're building, and reduce the noise.
What a superb video, your style for communicating these ideas is excellent. Thanks for sharing
thanks, i got some new vocabulary to weaponize at work. good stuff
We have a "REST API" but for some reason we change the API with every release. And sometimes we bump the version of single endpoints, not the whole API we don't use minor version. The versions before are immediately deprecated. And we will delete them when we sense they're no longer used. They tend to just return some JSON containing the data for each use case, no general resources or anything. The user's direct use cases defines what our api looks like. Totally fully REST.
Dylan, I've loved watching some of your tasks in the past, especially on "Enterprise" software and "TDD, where did we go wrong?". However in this case I'm not sure I agree with your conclusion or closing thoughts here. After having read the book on Hypermedia systems and learning htmx (I'm old enough to have lived some of the earlier days of the web), I think Hypermedia Driven Applications and Hypermedia in general still have a place.
In 2002, I was forced to integrate our enterprise system with SAP and of course they used SOAP. What a terrible experience. I never used it again unless it’s absolutely necessary. Since then I’ve always written dozens of web APIs with thousands of endpoints like Open API but because it was simple and it worked.
Why try to over define what it means? It’s a clean and simple way to get/set/delete resources from a server, way more simple and with less overhead than soap, which is a bloated piece of junk where the syntax takes up more space than the actual data. I actually prefer simple Telnet API , that way you can reduce overhead even further.
Proud to stand in the corner of using REST properly on the handful of projects Ive built for companies. Unfortunately they all suffered the same fate and now either dont exist or have been swolled up by THETHING
Great insights into the history of Rest and API design in general. Thank you Dylan
Thanks for sharing the concept in such a simple manner.
What was/is important about REST and REST operations (which can be used by not REST) is that it gives/gave a common language to use on APIs which everyone knew. That was huge it accelerated development, increased compatibility, and increased transferable skills.
That's funny, my experience has been the exact opposite. Having to consume external REST APIs slows down development tremendously. There is no "common language", every API is unique and structured differently. There is less compatibility because nothing is officially standardized, and the "skills" you acquire from writing a client for one API have very little application in writing a client for another. You're essentially starting from scratch every time.
@@Wishbone1977 that's why apis need to be documented. Every API whether REST or internal to the program must have documentation. Automated documentation is a thing.
@@Wishbone1977 and going back to my original point, they were the best alternative at the time.
@@wayhip Automated documentation _is_ indeed a thing. Now ask me how many of the "REST APIs" I had to consume 10 years ago used it.
Also, tooling is _important_ for productivity. And 10 years ago, there wasn't any proper tooling to help with making clients for REST APIs. Given the lack of standardization, making proper tooling was more or less impossible.
You say they were the best alternative at the time? For _external_ integration? No, they were not. Not by a long shot.
@@Wishbone1977 Not creating proper documentation is a programmer issue not an API issue. I did over 20 years in tech. Including programming (about half of it), DBA and sysadmin work, and QA. While talking to friends of mine with similar backgrounds we concluded that your typical programmer has the self discipline of incontinent baboons. Software Engineer my 4$$. Granted they often labor in bad work places but they shipped it without completing it. Their tech leads and managers let them get away with it.
Well said my good man! Salutaitons from Romania!
I've been using and creating APIs for well over a decade and somehow I never knew about the hypermedia stuff.
I was aware that it existed. I just never have time to investigate adding those links. If I have a an api endpoint for customer information /customer I will either have /customer/custid/invoices or /invoices/custid. Instead of parsing out the what can be done with the links, where all the heavy lifting has been done on the server side. The application code in browser implements the business logic, requests resources without hyperlinks and makes decisions about how to present the UI.
How though? Have you never once wanted to read the paper that invented the thing you're spending all your time on?
@@neildutoit5177 It is easy enough. Most of us start with just needing to get data from the backend to the font end and visa versa. If you can't do that all else is academic. Tutorials and libraries are focused on that. Everything related to hypermedia besides pagination is not needed. I need to get my app out the door. I know how I am coding my front end. Taking the time to duplicate my front end UI logic in hypermedia is counter productive to hitting deadlines. You can argue that is the case because the programmer does not understand Hypermedia. However, the reality is that 90%+ of REST API's are about shuttling data and not about using hypermedia properly.
Because nobody really cares to painfully navigate some "links" and guess their meanings when they can get a list of the actual, specified API endpoints for whatever they need to access anyhow.
@@clray123the point is you don't guess. It is defined. Rest is the difference between and your browser "knowing" that all stylesheets live at /style.css so the web page does not need to say. /favicon.ico is NOT rest, rel=icon *is*
Learned more in the first two minutes of this video than 99% of the programming content/tutorials. Thank you sir. Subscribed.
I'm old enough to remember when Z39.50 was most of the Internet traffic.
As a frontend dev, I love working with rest APIs and I can't be persuaded otherwise. They make my life easier as a dev.
Then you need to try graph ql.
Agree on most but GraphQL. It is an anti pattern, the same thing was done in the 90s when people were sending SQLs from application directly to sql server. Sure now you filter and secure access to data with graphql, but APIs should be explicit, 1:1 data/operation to use case.
"Same time, same channel, next week!" 📺
I still hate to co-opting of the HTTP error codes to report application errors. I know that in the OSI Model the HTTP layer is the application layer, but in practice we have built our own thing, that runs on top of HTTP, and so for most of this stuff if we are honest with ourselves HTTP is the transport layer now, and our specific messages that just happen to be exchanged via HTTP are the actual application layer. So no, I won't be putting my application errors into the transport. Its also bad coupling, What happens if you want to transmit message by something other than HTTP?
The usual compromise is to only indicate the category (success/no-success) and blame (client-problem/server-problem) through the HTTP code and do the rest with your application-specific error messages. Which you will need anyway to provide sensible aids for debugging.
Any rules that REST had has long been forgotten, we live in chaos land now where all responses now return 418 and we go make some tea
The rules never made sense
404 servers.
Sorry, I forgot to submit an RFC, my bad.
When I see the acronym HATEOAS, I often think "Aw, they've simply mis-spelled Halitosis."
HATEOAS
"The OpenAPI Specification (OAS)"
yep, that's how I feel
Lol !!!!!
I have worked a lot with SOAP and later REST and can confirm that both can be pretty complicated.
Thanks. Next time I know which paper to cite when calling my API "REST" lol.
Tuning in our brain frequency to tech? Idk tuning in is a colloquial phrase that just won't die.