3 ms·
What it means for an API to be RESTful
- gorkemyildirim 3mo agoOne thing missing from the hypermedia section: links do not have to live in the payload. RFC 8288 lets you carry the same relations in a Link header, and for some clients that is the only place they look. I advertise a markdown twin of a page as Link: </llms.txt>; rel="describedby"; type="text/markdown" for exactly that reason, no body parsing needed. Conditional requests feel like the other omission. ETag and 304 are part of the same "use HTTP as intended" argument, and they change client behaviour more often than whether someone hardcoded a route.
- mwigdahl 3mo agoWell, this inevitable flamewar will be a nice change from the pro-AI / anti-AI comment threads, at least...
- janpio 3mo agoAre you sure it is not just a AI authored rehash of the thousands of articles online that make the same points already?
- mwigdahl 3mo agoNice! Not 100% sure, but it reads very human to me. The only LLM-ism that jumped out at me was "An honest note before we continue", but that was the only time the word "honest" appeared. If it's not human-written it does an exceptionally good job of appearing so.
- andros 3mo agoLet me clarify: this was written by one person, by me. However, I received help with spelling mistakes, false friends, and a few connectors. Thank you!
- f6v 3mo agoI thought we were back in 2012 for a second after I read the title
- jaapz 3mo agoMaybe somebody should comment in this thread about GraphQL being better than RESTful API's - then I'd really feel right at home back in 2014
- yomismoaqui 3mo agoAlso a fiery Emacs vs Vi flamewar would be a nice palate cleanser right now.
- oldMobileOnWifi 3mo agoThere needs to be a fps or rts for that...
- oldMobileOnWifi 3mo ago100% thought the same thing. I miss the "you're doing it wrong!" opinion pieces of the early 2010s (and the flame wars they started...)
- krisknez 3mo agoGET /api/add-a-comment?message=disagree
- 1718627440 3mo ago'(to) comment' is already a verb.
- tgv 3mo agoGET, COMMENT, PUT, UPDATE, DELETE. Yeah, makes sense. Now we only need an alternative for PUT to backcronym CRUD. RIPOSTE?
- 1718627440 3mo agoI was referring to that the PATH could just be named /api/comment?... , because comment is already a verb.
- danshipt 3mo agoThis is exactly the kind of pointless discussion around rest apis
- 1718627440 3mo agoThe naming of endpoints is not specific to REST actually.
- sh0gg0the 3mo agoURIs/paths are meant to point at resources/documents and therefore ideally should not contain verbs.
- pixelatedindex 3mo agoThe word comment can be both a verb and a noun though. Are we pedantic enough yet? (:
- prologic 3mo agoIsn't this well defined already? https://en.wikipedia.org/wiki/REST https://en.wikipedia.org/wiki/REST > REST (Representational State Transfer) is a software architectural style that was created to describe the design and guide the development of the architecture for the World Wide Web. REST defines a set of constraints for how the architecture of a distributed, Internet-scale hypermedia system, such as the Web, should behave. And isn't it always misused, mis-represented basically all the time? Often confused with things that are basically just JSON API(s)?
- prologic 3mo agoIt's kind of interesting to go through the examples in the article, because it largely really describes a HAL-style JSON API really. It in parts also described the Web Linking Standard (RFC 8288) too.
- wun0ne 3mo ago> And isn't it always misused, mis-represented basically all the time? Often confused with things that are basically just JSON API(s)? The article makes this point.
- prologic 3mo agoI could be wrong, but I also think the article kind of gets it wrong too
- IshKebab 3mo agoAny descriptive term where people can't agree on what it means is completely useless. So there's no point trying to argue "REST means this" - the fact that so many people have done that already makes it pointless.
- CodingJeebus 3mo agoThe most bulletproof way to get a bunch of people on the internet to read your stuff is to tell them they're all wrong, never fails.
- deleted 3mo ago[deleted]
- recursivedoubts 3mo agoHere is how REST came to mean the opposite of REST: https://htmx.org/essays/how-did-rest-come-to-mean-the-opposite-of-rest/ https://htmx.org/essays/how-did-rest-come-to-mean-the-opposi... And here is why REST is probably largely pointless in machine-to-machine APIs: https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...
- andros 3mo agoA few years ago I would have 100% agreed with you, but now with LLMs they may have made sense again.
- recursivedoubts 3mo agoyes, I caveat that at the end: > Once we have strong AI, maybe the situation changes. But that’s what we’ve got today. However, I am doing research on AI and hypermedia and I'm skeptical that the late-bound, discoverable dynamic of it compete well with things like MCP, at least if you are using something like a ReAcT loop. I am publishing a paper on this soon.
- Octoth0rpe 3mo ago> They usually live under the _links parent. The example given in this section... is there actually a commonly used REST api that uses that particular key/structure? I wouldn't be _surprised_ if I came across that in some random API's documentation, but I hardly think it's the 'usual' thing to do. The article later claims that that style is from https://stateless.co/hal_specification.html https://stateless.co/hal_specification.html , which I think is a consultancy company whose major partners are all casinos (am I totally off on this?). The article also references (https://github.com/kevinswiber/siren https://github.com/kevinswiber/siren which adds detail re: http methods embedded in the _links structure, but I'm not sure why that repo should be considered authoritative. 1300 stars for a just a spec is actually not bad though I think, so maybe. Overall this article seems like slop produces from some kind of ai crawler that managed to dig up a couple of random links. I am glad that it mentions rfc9457 though.
- draw_down 3mo ago[dead]
- codinhood 3mo agoREST seems to bring out people who like to define specs and correct others on following the spec or not. There are many other things in tech like this. To be honest, I just kind of don't understand the point. Could my API be better following some of these rules the author presented? Probably. But by how much? Is it worth it? When someone else on my team disagrees do we go back and argue about the spec again? After 12+ years I'm just not sure anymore. If I'm using REST incorrectly (according to this article or others), but getting good results and everyone on the team is aligned, does it matter? I'm willing to have my mind changed this, maybe I'm missing something important
- 1718627440 3mo agoThe point is to externalize the thinking about the desired nirvana state, so that you don't need to thing about them, when you code your API.
- codinhood 3mo agoSure, ideally, but if no one can agree on the spec (as evidenced by the need for these types of articles,) then it's not really saving me much effort is it? Better to just pick something and go with it, then argue about the spec more
- regular_trash 3mo agoI think the problem is primarily if you publish a REST api for commercial consumption on some level. If people depend on your REST api, the "RESTfulness" of it affords you some level of inaccuracy when documenting how things work. But that said, I'm okay with it not following the spec as long as things are clearly documented to end users. We just went through an issue where a prominent CDN provider exposing a REST API we depend on broke REST in a very important way (i.e. NOT stateless). It's extremely annoying to try and construct clients around nonstandard APIs, and the more REST-y, the less annoying.
- locknitpicker 3mo ago> REST seems to bring out people who like to define specs and correct others on following the spec or not. There are many other things in tech like this. Yes, and this blog post is exactly yet another example. Some of the blogger's points are blatant violations of REST, such as the comments on URIs and api versioning. Yet, the blogger elevates their own personal misconceptions to the status of one true RESTful way. Ultimately it's all mostly irrelevant. All it matters is that the contract is specified and preserved and clients can consume services through a specific interface. Furthermore the pervasive use of openapi specs already crystalize the RPC approach to interfaces.
- dzonga 3mo agowhole thing about RESTful api - majority of people never understood it - few people like the htmx crowd tried to bring it up again to teach people the right way. but people who didn't understand rest some of them migrated to graphql or rpc.
- cjpearson 3mo agoMany years ago as a young developer I read Fielding's dissertation, Fowler's writings on the Richardson Maturity Model and even a book (don't remember the title) on the topic. Then I spent the next dozen years creating, reading, updating and deleting JSON APIs. Problem Details (RFC 9457) are useful and have made an occasional appearance, but actual hypermedia driven APIs with custom media types seem to be non-existent outside of example blog posts. It's much more common to instead see APIs overload lesser-used HTTP status codes with their own domain-specific meanings. But if I'm being honest, this sort of protocol crime almost never caused an actual problem in practice. The advocacy for "true REST" is missing a compelling argument and useful example of why it would actually be an improvement. Despite its prominence, for over 20 years almost nobody has used this approach. Why is that? I do still have an aesthetic appreciation for "true REST", but in practice I find the fact that nobody uses it to be mainly useful in ending bikeshedding discussions. Once you understand your API isn't RESTful to begin with, there's no longer any point in arguing if 411 or 412 is the more RESTful status code to use when a user attempts to order a product without specifying a quantity. (Spoiler: neither is correct) You simply send a 400 with Problem Details and call it a day. Ironically, this indifference may make your API just a little bit more RESTful.
- paulddraper 3mo ago> Despite its prominence, for over 20 years almost nobody has used this approach. Why is that? There is one highly successful use of REST: the World Wide Web. The Web/Web browsers are driven from hypermedia. (This is circular, as Fielding was looking at the web when making his dissertation.) Granted, Web browsers stand alone as an application with extreme flexibility. So REST is both highly common and very rare, depending on how you count.
- Octoth0rpe 3mo ago> I do still have an aesthetic appreciation for "true REST", but in practice I find the fact that nobody uses it to be mainly useful in ending bikeshedding discussions. Once you understand your API isn't RESTful to begin with, there's no longer any point in arguing if 411 or 412 is the more RESTful status code to use when a user attempts to order a product without specifying a quantity. I think I have a fundamental objection to the idea that Fielding and Fielding alone got to decide what REST is. While there hasn't been any kind of formal counterproposal, in some sense REST is what we make of it. Re: http 400 codes, I think many of us really liked the general principle of "use http semantics!" and applied that to error codes as well. That's agreeing with the principle and extending it in new ways that we like and are "truer" to the principle, even if it wasn't intended. In my mind this is sort of analogous to talking about the relationship between linux and unix. Linux is clearly not a genetic or copyright unix, but I've seen it said before that linux is the culmination of unix principles, in some cases extended beyond what was originally envisioned in ways that are innovative and genuine improvements (io_uring perhaps?). The REST we have today - http semantics, specific error codes, etc - may be significantly different from what Fielding may have wanted, but IMO it implements the parts that really distinguish it from the RPC world of API architecture, and I think we're generally happy with that.
- dSebastien 3mo agoCertainly not perfect build we wrote this spec for the National Bank of Belgium a few years ago. Served us well. https://github.com/NationalBankBelgium/REST-API-Design-Guide/wiki https://github.com/NationalBankBelgium/REST-API-Design-Guide...
- somat 3mo agoREST is an inherently human technology, almost superfluous for API(emphasis on Programming Interface) usage. I guess it does not strictly have to be, especially with our modern LLM's But REST can best be summed up as "ship the human interface required to handle a state with every state". For a strictly programming interface, this interface coupled with the state is inefficient and mostly pointless(the application already knows how to handle the state, it does not have to figure it out) and is better served by a more focused mechanical transfer. With how narrow this scope ends up being I can understand how most of the tech industry collectively had what appears to be a collective brain fart when Fielding said "hey this web thing is doing something really novel in the field of application design, lets talk about it" and went "herp derp, REST == HTTP, sounds good to me". I mean I understand it, but still find it funny.
- chasingthewind 3mo agoI was a REST purist for a while and the purer I got the more unhappy I was. Hypermedia standards like Siren and HAL just made things miserable no matter how hard I tried to make them work. I think the REST Architectural Pattern is great but I don't use it anymore. Instead I create ROUSED services. Resource Oriented Unconstrained Sensible Enterprise Services Resource Oriented because the very best thing about REST is the tendency to focus on resources and collections of resources and how you can interact with them sensibly. Unconstrained because I don't let some specification control how I work. Sensible because things still need to be internaly consistent and well thought out. Enterprise because the fact is I'm always making these services for some 'boring' business use case. Services that provide some specific set of bounded capabilities within the usual messy ecosystem present at a SaaS software company. I think we owe a lot to Roy Fielding for the potent ideas but as others have argued eloquently, reality sets in and you have to adapt to circumstances.
- montroser 3mo ago> You must not store or reuse URI structures in the client. An API could change them without notice, and your client would obviously stop working. Instead, parse the links and follow the relative identifiers (rel). This part is a complete and total fairy tale. No API consumer wants to operate in a world where the API could "change without notice." In real life, no provider would expect that of their clients, and no client would seriously accept that before every API request, they must first hierarchically rediscover the provider's dynamic url scheme of the moment, in order to traverse down to resource they ultimately want to request. There has never been any serious commercial or high-traffic API that implemented this. And it's not because "lame corporate tech teams aren't hip to the true meaning of REST" -- it's because "it doesn't actually make sense to do it that way so nobody wants it to work like that."
- gwbas1c 3mo agoEvery time I look at a "how to do pure REST", it seems like doing REST correctly is building a self-describing database instead of making an API that does a thing. Here's the thing: Customers don't care if your application does REST correctly or not. They only care if your application works. API consumers care about REST only as far as the HTTP API makes sense and follows well-known and well-understood conventions. I don't think I've ever come across a self-describing API in the wild where I have to constantly self-discover URIs. (And frankly, if someone proposed something like this I'd laugh at them.) It's just needless overengineering.
- pan69 3mo agoAnyone working in an organisation where teams are trying to map business logic errors into HTTP status codes? Wasn't Fieldings original dissertation meant as a formalisation of the web? I.e. it had nothing to do with APIs until later, when that became popular in the mid 2000s? The amount of nonsense conversations / meetings I have been in over the years around designing "RESTful" APIs, endless discussions, I can no longer keep count. Because, unless you're working on an academic research project, everything in REST becomes a compromise. At this point I am starting believe that REST has done more harm than good for the industry.
- aezart 3mo agoAt my job REST just means "not SOAP" basically. No other standardization.
- cco 3mo agoThe longer I work with and write APIs, the more and more I believe everything should be a POST.
- oldMobileOnWifi 3mo agoThat's actually really correct in the most wrong way possible. I've worked with one too many endpoints that don't care about UPDATE, DELETE, and whatever else beside POST exists, while relying on body data to do the "what department are you looking for" requests.
- cco 3mo agoYes, I also balked when I originally encountered this pattern at a previous co. And I think agree with your point, "correct in a wrong way"? Yeah, everything as a POST is wrong, but it is less wrong and more clear to just ignore REST because the assumptions are broken so often it just makes it more complicated. Just POST everything and make it clear in the URI + bodies what is happening.