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.
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 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.
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 ...
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.
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.
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.
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).
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.
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.
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 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".
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.
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.
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.
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.
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 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
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 ;-)
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.
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.
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.
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 ;)
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.
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.
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.
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.
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)
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.
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.
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.
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
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.
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.
@@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.
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.
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.
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.
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 person who created it has more weight on what it mean. True. Language evolves. Also true. I've tried hard to reconcile these things. A Neil Gaiman quote comes to mind: "Whether we are creating works of art and literature or technologies, we must be aware that we are creating something that serves as a template for someone else to fill it on." I think this is where I am landing - at one time an APIs must include HATEOS to be truly REST per Roy Fielding. But REST APIs are transformative enough that in my mind they have reached the level of art and as such, they no longer belong exclusively to the creator. If we have come to a place where REST API means something different, then so be it. Doing PUT, POST, content negotiation and proper error codes? Do you have an OpenAPI spec document I can look up and figure out how to use your API? Great. Call it REST. I can agree.
The conclusion is what is accurate--that REST (for the most part) works pretty well for API's. There are some caveats, and not all business cases work well with it, but in general its good enuff, especially when as you said, 5-years is about the life span of a code base.
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*
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.
The hypermedia part of the concept is effectively an optional subtype of a generic API concept. In practice, this ISN'T used as an API (Application Program Interface - a way for one application to request services of another), but as an integral part of a single application - a website containing web pages, with possible links to other websites. The GET, POST, PUT, etc. HTTP methods are used for API calls, but those calls don't generally return hypermedia, they send or return formatted information. So, in modern parlance, 99% of all official REST "APIs" are just webpage calls. And of the APIs that use HTTP protocol, 99% do not qualify under the original definition of REST. But they use the exact same calling and return protocol. One advantage of the HTTP protocol as a wrapper for APIs is that it is easier to test such an API, and you can have an entire standard web protocol stack supporting it. One disadvantage is that it requires a relatively heavy stack, and is innately tied to TCP, meaning that you lose the other protocols in TCP/IP. You could call these APIs SHAPE (Stateless HTTP API Protocol Environment), or any other acronym, but nost programmers call them REST, as they are identical except for the return values. And the API type is not determined by the input and output but by calling method (where REST with hypermedia shares the same method as data queries). Would the inventor really classify an API that returns a webpage based on whether the returned webpage has hyperlinks?
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 😬🤷🏽♂️
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
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.
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.
The hypermedia part is very important and is the core of the entire web. It's just that people forgot. We have an incredibly popular and easy to use hypermedia language - HTML. Too often people lament at the complexity of extracting hypermedia from JSON and the infrastructure required. Well, yes, converting hypermedia in JSON to hypermedia in HTML is difficult. The question is - why do it? Why parse structures and pick out links? Why not just use HTML instead and just... throw it at the browser? It can do the parsing just fine. Crazy, some think, but devilishly easy to implement, incredibly fast, and unbelievably simple.
Note that REST was specifically designed for hypermedia transfer through caching proxies. 90% of the decisions made there were for improving the delivery of large text and image and video and etc. Think "this is how you structure your CDN" rather than "this is how you structure your customer login."
Links are redundant when APIs are designed to serve a particular front-end application with Javascript. For example, if you send current_page and page_count in an API response, it is easy to construct the exact URL for any page you want. The same is the case for any other page where an id or some specific value is just a query parameter in a URL. I will still call them REST APIs because everyone understands what I am talking about.
the architecture must be selected to suit the needs, whether it is SOAP, OPC UA, gRPC, REST,... any. not just blindly following the trail and putting the thing to every hole - it must fit!
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.
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.
The problem with REST APIs (and Soap and most HTTP based APIs) is the fact that HTTP is an ASCII protocol. So all variables sent in the request and response are simply ASCII, but when writing APIs you need some way to know what types those variables represent. And most of the work in today's web applications come from converting the variables in the api calls to the appropriate types in the language you are using on the front or back end. Which is where so much of the plethora of frameworks have come into play from Spring, to Angular and Typescript for web programming. And the fielding paper on REST is actually more of a description of HTTP as an implementation of RESTFUL principles not so much a general architecture for building web services. But using HTTP for web servers was attractive because you had a standard representation format in HTML a standard for scripting in java script and a standard for transport in HTTP for which browsers were the default client supporting those standards. All of those things just made web services using HTTP like REST popular, despite its limitations.
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.
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.
That's the entire use it is meant to have imo. The presentation layer, the browser, calls the api, and acts on the result. The standard HTML specs fall just short of making it much much more useful, but libraries like HTMX extend the browser so they can act on the result. Needing no out of band information. No reverse engineering nothing like that. It's again, imo, not meant for Machine to Machine communication. Though it can probably work about as well as JSON for that, I think.
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.
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"
In my 25 years of experience I've yet to meet a REST purist who was good at anything but making ppt slides.
I always like to see a dev who's not dogmatic. It's an engineer's approach, and I respect it a lot.
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.
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 👏
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 RUclips videos are as well researched and full of background as your talks, another awesome video Dylan
This, 100%
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.
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.
My favorite part is that you ended the video reminding us to look after each other.
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
What a wonderful gem of a channel I’ve just discovered :)
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).
this was really well explained and you should be proud of the work you put into this :)
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.
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.
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 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".
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.
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.
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.
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.
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 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.
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 ;-)
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.
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.
Glad this came up in my recommended feed. I will be tuning in again.
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.
Bravo! Excellent video! you take the words out of my mind and nailed them to the youtube post.
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.
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 ;)
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.
Loved this breakdown, subbed!
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.
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 had no idea you had a channel!!
I love your presentations! some of my faves
great video. subscribed
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.
Finally some sense! Great info thanks for sharing and providing light in this APIs Jungle
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.
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.
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)
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.
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.
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.
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.
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
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.
What a superb video, your style for communicating these ideas is excellent. Thanks for sharing
randomly stumbled across this video, but Dylan seems cool. I will definitely watch more videos of this channel.
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.
Thanks for sharing the concept in such a simple manner.
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.
HTTP...I saw what you said there. The overdub was close to perfect ;)
citation needed is lowkey the funniest thing I've seen in a hot minute
Great insights into the history of Rest and API design in general. Thank you Dylan
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.
thanks, i got some new vocabulary to weaponize at work. good stuff
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.
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.
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.
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... :)
The person who created it has more weight on what it mean. True. Language evolves. Also true. I've tried hard to reconcile these things. A Neil Gaiman quote comes to mind: "Whether we are creating works of art and literature or technologies, we must be aware that we are creating something that serves as a template for someone else to fill it on." I think this is where I am landing - at one time an APIs must include HATEOS to be truly REST per Roy Fielding. But REST APIs are transformative enough that in my mind they have reached the level of art and as such, they no longer belong exclusively to the creator. If we have come to a place where REST API means something different, then so be it. Doing PUT, POST, content negotiation and proper error codes? Do you have an OpenAPI spec document I can look up and figure out how to use your API? Great. Call it REST. I can agree.
Well said my good man! Salutaitons from Romania!
Your ending about language evolution was perfectly illustrated
The conclusion is what is accurate--that REST (for the most part) works pretty well for API's. There are some caveats, and not all business cases work well with it, but in general its good enuff, especially when as you said, 5-years is about the life span of a code base.
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*
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.
The hypermedia part of the concept is effectively an optional subtype of a generic API concept.
In practice, this ISN'T used as an API (Application Program Interface - a way for one application to request services of another), but as an integral part of a single application - a website containing web pages, with possible links to other websites.
The GET, POST, PUT, etc. HTTP methods are used for API calls, but those calls don't generally return hypermedia, they send or return formatted information.
So, in modern parlance, 99% of all official REST "APIs" are just webpage calls.
And of the APIs that use HTTP protocol, 99% do not qualify under the original definition of REST.
But they use the exact same calling and return protocol.
One advantage of the HTTP protocol as a wrapper for APIs is that it is easier to test such an API, and you can have an entire standard web protocol stack supporting it.
One disadvantage is that it requires a relatively heavy stack, and is innately tied to TCP, meaning that you lose the other protocols in TCP/IP.
You could call these APIs SHAPE (Stateless HTTP API Protocol Environment), or any other acronym, but nost programmers call them REST, as they are identical except for the return values. And the API type is not determined by the input and output but by calling method (where REST with hypermedia shares the same method as data queries).
Would the inventor really classify an API that returns a webpage based on whether the returned webpage has hyperlinks?
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 want to build a RUclips controller from an old TV tuner now.. just so I can tune in to this channel again.
Learned more in the first two minutes of this video than 99% of the programming content/tutorials. Thank you sir. Subscribed.
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.”
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
I will put this video in my list of "Informatics Philosophies"
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.
Just a note of appreciation for "The Consolidated Cheese and Diesel Corporation" at 03:56 🤣
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.
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.
Well put - so many people don’t see this.
The hypermedia part is very important and is the core of the entire web. It's just that people forgot. We have an incredibly popular and easy to use hypermedia language - HTML. Too often people lament at the complexity of extracting hypermedia from JSON and the infrastructure required. Well, yes, converting hypermedia in JSON to hypermedia in HTML is difficult. The question is - why do it? Why parse structures and pick out links? Why not just use HTML instead and just... throw it at the browser? It can do the parsing just fine. Crazy, some think, but devilishly easy to implement, incredibly fast, and unbelievably simple.
Note that REST was specifically designed for hypermedia transfer through caching proxies. 90% of the decisions made there were for improving the delivery of large text and image and video and etc. Think "this is how you structure your CDN" rather than "this is how you structure your customer login."
Links are redundant when APIs are designed to serve a particular front-end application with Javascript. For example, if you send current_page and page_count in an API response, it is easy to construct the exact URL for any page you want. The same is the case for any other page where an id or some specific value is just a query parameter in a URL. I will still call them REST APIs because everyone understands what I am talking about.
the architecture must be selected to suit the needs, whether it is SOAP, OPC UA, gRPC, REST,... any. not just blindly following the trail and putting the thing to every hole - it must fit!
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.
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.
Missed opportunity here not titling the video “Turns out REST APIs weren't the answer (and that's 200)”
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!
You promised me JSON and then sent XML
😂
Thanks. Next time I know which paper to cite when calling my API "REST" lol.
The problem with REST APIs (and Soap and most HTTP based APIs) is the fact that HTTP is an ASCII protocol. So all variables sent in the request and response are simply ASCII, but when writing APIs you need some way to know what types those variables represent. And most of the work in today's web applications come from converting the variables in the api calls to the appropriate types in the language you are using on the front or back end. Which is where so much of the plethora of frameworks have come into play from Spring, to Angular and Typescript for web programming. And the fielding paper on REST is actually more of a description of HTTP as an implementation of RESTFUL principles not so much a general architecture for building web services. But using HTTP for web servers was attractive because you had a standard representation format in HTML a standard for scripting in java script and a standard for transport in HTTP for which browsers were the default client supporting those standards. All of those things just made web services using HTTP like REST popular, despite its limitations.
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.
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.
That's the entire use it is meant to have imo. The presentation layer, the browser, calls the api, and acts on the result. The standard HTML specs fall just short of making it much much more useful, but libraries like HTMX extend the browser so they can act on the result. Needing no out of band information. No reverse engineering nothing like that.
It's again, imo, not meant for Machine to Machine communication. Though it can probably work about as well as JSON for that, I think.
I have worked a lot with SOAP and later REST and can confirm that both can be pretty complicated.