[HN Gopher] How Did REST Come to Mean the Opposite of REST?
___________________________________________________________________
How Did REST Come to Mean the Opposite of REST?
Author : edofic
Score : 125 points
Date : 2022-07-18 17:44 UTC (5 hours ago)
(HTM) web link (htmx.org)
(TXT) w3m dump (htmx.org)
| [deleted]
| stuckinhell wrote:
| Software Development is like water filling a container. It's
| always water but its form takes the shape of its container.
|
| After doing this for 15+ years, I tell my junior developers to
| take it easy on the "proper way" of doing things. It will change,
| people will argue, and money talks.
| Frost1x wrote:
| I'd like to see a lot more humility on certainty of approach
| than the absolutism we often see. There's often a handful or
| more ways to do anything, why is there so much certainty in all
| contexts of the _correct_ way. The correct way is often best
| defined by the unique context a given piece of software is
| developed within. Tradeoffs take into account more than
| technology alone.
| alecbz wrote:
| dhh has a talk about this general idea.
|
| Writing software is such a _human_ thing. It has so much more
| in common with writing than it does with other kinds of
| engineering.
|
| Most of what we're doing has to do with how to lay things out
| so that it's clear and easy for other humans (including the
| humans that write code) to understand, interact with, and
| modify. Any time you're dealing with humans brains, there's
| going to be a lot of complex subtlety in terms of what the
| "best" approach is.
|
| But because it's software "engineering", people think we need
| to have fairly hard-and-fast rules about the right way to do
| everything.
| jrochkind1 wrote:
| This is undated, but I could swear I had read it before years
| ago! But I can't find an earlier publication, I guess I read a
| similar thing!
| mixmastamyk wrote:
| The author writes on the subject somewhat often and includes
| ideas from earlier posts. This must be the latest version
| because it had a link to few-day-old HN thread.
| xcambar wrote:
| I feel old for I have witnessed many of these battles. But I feel
| that I have seen history.
|
| There's nothing wrong in this article, in the sense that
| everything's correct and right. But it is an old person's battle
| (figuratively, no offense to the author intended, I'm that old
| person sometimes).
|
| It would be like your grandparents correcting today's authors on
| their grammar. You may be right historically and normatively, but
| everyone does and says differently and, in real life, usage
| prevails over norms.
|
| Same goes for REST.
| recursivedoubts wrote:
| I see in your eyes the same fear that would take the heart of
| me
|
| A day may come when the courage of old web developers fails,
|
| when we forsake our old, RESTful network architecture
|
| and break all bonds of HATEOAS
|
| but it is not this day
| russellbeattie wrote:
| Articles like this are good to show how fads and buzzwords in
| tech take on a life of their own. Hopefully there are some
| younger devs in this thread who can learn from it.
|
| Us older guys have to do the opposite. As we see these things
| come and go, we get jaded and start to dismiss new techniques
| as fads. I shudder to think of how much wasted effort I put
| into "Enterprise JavaBeans" and "XSL Transforms". Years later,
| I took a look at React when it first launched, dismissed it as
| crap because of the mess it made in the DOM back then, and then
| ignored it. It took me a few _years_ until I realized I was
| wrong and it was going to stick around.
| icedchai wrote:
| You were right and wrong. Just because something is crap
| doesn't mean it won't stick around...
| xbar wrote:
| I was there, at the Tannhauser Gate....
|
| Like you I saw the wranglings over this meaning. And today I
| look at the documentation and see HTTP+JSON RPC and I still
| FEEL "that's not REST" but whatever.
| wwweston wrote:
| The descriptivist approach has a lot of merits when it comes to
| language -- to no small extent, words _do_ mean what people
| think they mean; this is part of what it means for words to
| have any meaning at all, and when entire cultures let the
| meaning of a word drift it 's hard to figure out what ground to
| stand on in order to say they're _wrong_.
|
| And yet... right or wrong, something substantial is lost when
| "literally" fades into a figurative intensifier.
|
| Same goes for REST.
|
| There's little immediate problem in the misappropriation of the
| term. The problem is how few engineers spend anything more than
| literally zero time actually thinking about the potential
| merits of the original idea (and quite possibly less). Not even
| talking about the people who spend time thinking about it and
| reject it (whatever points of contention I might raise on that
| front), just the sheer volume of devs who sleepwalk through API
| engagement or design unaware of the considerations. That's the
| casualty to be concerned about.
| marcosdumay wrote:
| This would be a better point if actual REST was something
| widely used. Then we would have lost a useful word.
|
| But personally, I think I have never seen any actual REST
| that wasn't just browser-oriented HTML. So using the word for
| the API pattern is quite ok.
| xcambar wrote:
| > And yet... right or wrong, something substantial is lost
| when "literally" fades into a figurative intensifier.
|
| Yes, but wisdom is to avoid to conflate "lost" for
| "degraded".
| jaaron wrote:
| This is me, 100%. I've seen enough to realize that progress is
| largely each generation re-thinking and re-mixing the previous
| generation's problems. Sometimes the remix makes things better,
| but plenty of times, older generation look at what's being done
| and says, "wow, you really don't understand what this was
| originally intended for" and there's a pain in that
| misunderstanding and inefficiency, watching work get redone,
| wars being refought, and hard won triumphs being forgotten.
|
| That goes for technology, words, political concepts, music...
| prox wrote:
| The amount of people that think that _insert musician here_
| had this great original song is one of the most encountered
| fallacies in my daily life and online.
|
| Not only that, people tend to compare in word and concept
| from the newer song to the older song! "Hey wow this song
| from 19xx sounds just like this new song I love"
|
| No you fool, your new song sounds like the previous one :P.
| Causality matters!
| rapind wrote:
| Like the thousands of songs using Pachelbel's Canon.
| xcambar wrote:
| Since you have decided to expand beyond tech, I'd like to
| share a possibly optimistic perspective.
|
| We are instructed to think that progress is a straight line.
| Without any surprise, it is not. But I like to picture it
| with a direction nonetheless... upwards. So as it's not a
| straight line, I see it as a pulse, with its ups and downs,
| the ups usually being mild and the lows potentially
| dramatically sharp.
|
| But still somehow going up.
|
| ---
|
| On the current and future challenges: I am mortified about
| what we did and are doing to the planet and horrified to
| witness the political tensions in Europe (not only the war,
| because Europe has seen Crimea, the Balkans, and war never
| stopped after 1945, but now, there are severe risks of
| expansion). Also, I do not believe in tech as a means to
| solve our problems, never did, never will.
|
| So maybe my tiny optimistic pulse trending upwards is too
| candid and naive but at the moment, maybe blind with despair,
| I hold on to this idea.
| tuetuopay wrote:
| this reminds me when I was learning programming. I was
| talking about it to my granddad (that pioneered a few things
| computer-related), and he asked me "okay great you program in
| C, but do you write computer programs or applications?". I'm
| pretty sure this nuance mattered in the mainframe-era, but 15
| year-old me did not get it at all, and frankly, I'm still not
| sure what he meant, despite doing it for a living. But
| nowadays the distinction disappeared (did the two merge? did
| one fade?), and the REST APIs nuances did also disappear to
| only keep the parts that matter: those that made this model
| successful.
| derefr wrote:
| The thing that confuses me with semantic drift, is that nobody
| stops at any point to make a word for what the other word
| _used_ to mean. It 's very hard to refer, at this point, to
| "the thing that people meant when they said REST ~15 years
| ago." Can't we just come up with another jargon term for that,
| that _isn 't_ being squatted on?
| NAHWheatCracker wrote:
| People do try to come up with new terms. I've seen such
| suggestions blog posts and comment boards.
|
| The issue is getting everyone to agree with your new word or
| to even recognize the problems of semantics.
|
| Many people also deliberately misuse the existing terms to
| get advantages. For example, DevOps in your title gives you a
| higher pay despite often being materially the same as a pure
| operations role or sys admin.
| int_19h wrote:
| That's usually a sign that the thing that didn't get a new
| word is not actually all that useful or interesting.
| xcambar wrote:
| Highly debatable. A (too quick?) Darwinist perspective
| would tell us that the original ReST was not fit. And the
| "new" ReST (aka, JSON-RPC) is more fit.
|
| Fit in its current ecosystem, of course.
| polotics wrote:
| Good point. My only idea would be to say it in-extenso:
| representational state transfer...
| rrauenza wrote:
| I feel like the author has conflated hypertext with html.
|
| The REST interface should be self describing, but that can be
| done in JSON.
|
| If you go to Roy Fielding's post... there is a comment where
| someone asks for clarification, and he responds:
|
| > When I say hypertext, I mean the simultaneous presentation of
| information and controls such that the information becomes the
| affordance through which the user (or automaton) obtains choices
| and selects actions. Hypermedia is just an expansion on what text
| means to include temporal anchors within a media stream; most
| researchers have dropped the distinction.
|
| > Hypertext does not need to be HTML on a browser. Machines can
| follow links when they understand the data format and
| relationship types.
|
| So, to me, a proper format is something like...
|
| id: 1234
|
| url: http://.../1234
|
| name: foo
|
| department: http://.../department/5555
|
| projects: http://.../projects/?user_id=1234
|
| This is hypertext in the sense that I can jump around (even in a
| browser that renders the urls clickable) to other resources
| related to this resource.
| recursivedoubts wrote:
| No, I haven't. JSON can be used as a hypermedia, and people
| have tried this, but it hasn't really worked out very much and
| the industry trend is against it, towards a more RPC-like
| approach.
|
| I'm using HTML as an example to demonstrate the uniform
| interface constraint of REST, and showing how this particular
| JSON (and, I claim with confidence, most extent JSON APIs) do
| not have a uniform interface. Which is fine: the uniform
| interface hasn't turned out to be as useful when it is consumed
| by code rather than humans.
|
| There are good examples of successful non-HTML hypermedias. One
| of my favorites is hyperview, a mobile hypermedia:
|
| https://hyperview.org/
| wvenable wrote:
| I'm old enough to remember WML which was a mobile non-HTML
| hypermedia standard. I enjoyed using it but it was obvious
| putting an HTML browser on a phone was always going to win
| out.
|
| Hyperview isn't that interesting because it's a non-standard
| proprietary technology that isn't really "on the web". So you
| either have something like that, an actual full-featured HTML
| browser, or have something consuming a fully defined JSON
| API. It doesn't feel like there's anything interesting about
| non-HTML user agents on the web. HTML automatically makes
| them all irrelevant.
| recursivedoubts wrote:
| hyperview is a hypermedia that exposes native mobile
| features directly within the hypermedia
|
| you wouldn't create an internet out of hyperview-apps,
| rather it is a way for you, a developer of a mobile
| application, to get the benefits of a hypermedia approach
| (e.g. versioning becoming much less of an issue, vs. app-
| store updates) while not giving up on native mobile
| behavior
|
| it is open source, and I think it's one of the most
| innovative uses of hypermedia I've seen in the last decade:
|
| https://github.com/instawork/hyperview
| shadowgovt wrote:
| In practice, this turns out to be a painful way for a client to
| access the data; instead of a single fetch to get the relevant
| information, we're now doing multiple fetches and collating the
| results client-side. For this kind of data access, I'd
| recommend either
|
| a) just denormalizing the field contents if you know what the
| client needs them for
|
| b) supporting GraphQL if you want to support a general-purpose
| query endpoint
| derefr wrote:
| REST says nothing about normalization. In fact the opposite
| -- a _resource representation_ in REST is the very same thing
| as a graph in GraphQL, or a view in SQL: an arbitrary remix
| of underlying data. REST is meant to be a projected view-
| model layer for web clients to interact with underlying data
| through; it 's not meant to inform or be strongly bound to
| the shape _of_ that underlying data.
| a3w wrote:
| I found that json-ld, json-hal and other "describe your json"
| standards were needed to make json human readable-ish. I hate
| that there are many competing standards and the link syntax
| feels clumsy. JSON5 for "add comments, allow ES6 features" was
| perfect for private and in a small team use for a while.
|
| No one seems to listen to the JSON inventor, who said he
| regrets creating a misnomer name and no successor should use
| the same naming parts, since it neither dependent on or
| compatible with JavaScript, nor was it only useful for storing
| and/or describing objects. (I am paraphrasing from my memory on
| his reasoning on both points.)
|
| Open API 3 solved that problem for me, transforming JSON-RPC
| into a documentented API.
| Barrera wrote:
| Several commenters take the position that the distinction doesn't
| matter. This is "an old person's battle." What matters is getting
| things done.
|
| I'm not so sure. For one thing, it's of both theoretical and
| practical interest to trace the path of how a technical term
| comes to mean its opposite over time. If you're in the business
| of creating technical terms (everyone building technologies is),
| you might learn something by studying the REST story.
|
| For one thing, Fielding's writing is not exactly approachable.
| REST is described in a PhD dissertation that is dense, packed
| with jargon and footnotes, and almost devoid of graphics or
| examples. His scarce later writings on REST were not much better.
|
| Others who thought they understood Fielding, but who could
| write/speak better than him, came along with different ideas.
| Their ideas stuck and Fielding's didn't because he wrote like an
| academic and they did not.
|
| The other thing that happened is that the technological ground
| shifted. To even begin to understand Fielding requires forgetting
| much or all of what one knows about modern web technologies. Part
| of that shift is the timing of Fielding's rediscovery with deep
| frustration over XML/RPC.
| RandyRanderson wrote:
| REST, SCRUM, Agile, etc these are just cargo cults built from
| temerity (in the blindness sense).
| xcambar wrote:
| I wrote that it is an old person's battle.
|
| And I'd like to clarity that never did I mean that the
| knowledge and history fueling this so-called battle was meant
| to the trash.
|
| Quite the opposite actually. As a self-described old person, I
| much appreciate the historical perspective and the subtleties
| and the changes the term has seen.
| potamic wrote:
| Great article. Calling APIs RESTful because they return JSON has
| always been a peeve of mine. But here's the question though, why
| do APIs need to be RESTful? What is the need for a client to have
| no knowledge of the server, if the server can also provide logic
| that can run on the client. In some sense, one could argue that a
| service that provides both raw data and client logic to transform
| raw data to hypermedia, is still very much in the spirit of REST.
| Webapps by definition must satisfy this requirement, so it is
| moot to be asking if a webapp follows RESTful principles. Of
| course it does, it runs on the web! Native apps on the other hand
| have sure ruined everything.
| zmmmmm wrote:
| > What is the need for a client to have no knowledge of the
| server, if the server can also provide logic that can run on
| the client
|
| It's a measure of decoupling I think. If your client started
| out with no knowledge of the server and still managed to work,
| then it will still work even when the server is upgraded,
| restructured, etc etc.
|
| Of course, having every client just started at the root URL and
| then navigate its way to what it needs by effectively spidering
| the server just aint practical in any meaningful sense. But in
| small ways and critical places it is still possible to follow
| this pattern, and to the extent you do, in return you get a
| level of decoupling that is a useful property to have.
| treis wrote:
| IMHO, they've wildly missed the mark. APIs, as colloquially
| known, can't be RESTful as they define it because the client
| systems aren't AI based and can't follow links. To use their
| example: <html> <body>
| <div>Account number: 12345</div> <div>Balance:
| $100.00 USD</div> <div>Links: <a
| href="/accounts/12345/deposits">deposits</a> <a
| href="/accounts/12345/withdrawals">withdrawals</a>
| <a href="/accounts/12345/transfers">transfers</a>
| <a href="/accounts/12345/close-requests">close-requests</a>
| </div> <body> </html>
|
| I can navigate to that page and because I know English can
| follow links to my withdrawls and deposits. A computer can't.
| The client program needs to have an understanding of withdrawl
| and deposit in order to function. The only way to do that
| involves coupling the client to the server.
| masklinn wrote:
| > The client program needs to have an understanding of
| withdrawl and deposit in order to function. The only way to
| do that involves coupling the client to the server.
|
| Rest never denied that coupling, it defined that coupling at
| the content-type level.
| treis wrote:
| Can you expand? I don't think I understand.
| deanCommie wrote:
| And that's even before we get into:
|
| * Localization * Accessibility * Different clients *
| Different presentations for different contexts.
|
| The whole premise of RESTful hyper-media driven APIs
| described in this article is predicated on "The One" client
| talking to the server. Our modern world is not this.
| zdragnar wrote:
| Why should a server limit itself to a single client? At some
| point, you might want to make a mobile app companion to your
| site, or you might white-label your services in partnership
| with another company who will need to use your APIs, or any
| number of other common scenarios.
|
| A hobbyist / small company doesn't _need_ to have RESTful APIs.
| The whole point is to design them so that they play well with
| others, and when you get to that point, you (or more likely the
| people who depend on you) will wish you had.
| femto113 wrote:
| There are two fundamental reasons HATEOS just doesn't work in
| practice. The first is that most services can't easily or
| reliably know their own absolute URLs , and HATEOS (and the
| behavior of many HTTP libraries) is inconsistent around relative
| URLs, so hacky and unmaintainable response rewriting gets applied
| at various levels. The second is that if you are diligently
| following a convention for how paths are constructed it's utterly
| redundant information--you can simply synthesize any path you
| need more easily than you can grok it out of HATEOS. The
| reasonable bits of REST that are left are not just HTTP verbs and
| JSON, but significantly the use of entity type names and ids in
| the path portion of the URL rather than in query parameters.
| kelseyfrog wrote:
| An earnest answer? Because few people have taken the couple
| hours(?) and read Roy Fielding's dissertation from start to
| finish. The biggest likely reason for not doing so is that
| frankly a bunch of people simply don't care, and why should they.
| There's very little incentive to do so. In fact, the fewer people
| that do, the less of an incentive there is - there is no one can
| call them out on it and they can reap the rewards of calling an
| API RESTful despite the accuracy of the statement.
|
| Having worked in an organization where people were very familiar
| with the academic definition of REST, the biggest benefit of
| being a backend developer was that when client-side folks
| depended on nonRESTful behavior, we had some authority to back
| that claim. It gave us leeway in making some optimizations we
| couldn't have made otherwise, and we got to stick to RFCs to
| resolve many disputes rather than use organizational power to
| force someone to break compliance to standards. I suppose it
| meant that we were often free to bikeshed other aspects of design
| instead.
| trixie_ wrote:
| The dissertation is neither a specification or a standard which
| has led to decades long bickering of what 'REST' really is.
|
| Edit: See how this post has zoomed to hundreds of comments in
| just minutes by people arguing the 'one true REST'. The
| situation is insufferable.
| fennecfoxen wrote:
| I tend to find it helpful to ask, "is this proper REST as in
| HATEOAS, or is just 'REST-ish'?" It's usually just REST-ish:
| predefined URL patterns, roughly 1:1 with specific resource-
| APIs; they care about your HTTP verb and return JSON (but
| usually not with a lot of URLs in that JSON).
| kelseyfrog wrote:
| It's funny because HATEOAS violations were single-handedly
| the most common violation made by the client team during my
| time there. They loved hard coding URLs and willfully
| ignoring hypermedia.
| ess3 wrote:
| I feel like the biggest reason why REST failed is because it's
| just not useful from a business point of view. Like how will I
| put my logo and brand colors over all of this.
| danielovichdk wrote:
| Seems strange to me that people fight over REST since it is very
| clearly communicated in the mentioned PhD dissertation.
|
| I fully understand the movement of complexity, historically
| belonging on the server, shifted just as much on to the client,
| but that's not a discussion of being restful - it's not restful
| to have the client determine application state so to speak - the
| server does that for you.
|
| In the sense of catering multiple clients via an API is of
| tremendous value but you still moved the complexity on to the
| client - you cannot argue against that.
|
| I find it fascinating to have at least blobs of
| state/representation being served without having to fiddle with
| inner workings of an API and simply rely on the API to give me
| what I must show the user.
|
| I am in the HATEOES camp, it sit well with me. But that's just me
| janci wrote:
| Because HATEOAS is stupid for client-server communication.
|
| It mandates discoverability of resources, but no sane client will
| go around and request random server-provided urls to discover
| what is available.
|
| On the other hand, it does not provide means to describe
| semantics of the resource properties, nor its data type or
| structure. So the client must have knowledge on the resources
| structure beforehand.
|
| Under HATEOAS the client would need to associate the knowledge of
| resource structure with a particular resource received. A
| promising identifier for this association would be the resource
| collection path, i.e. the URL.
|
| If the client needs to know the URLs, why have them in the
| response?
|
| Other problems include creating new resource - how the client is
| supposed to know the structure of to-be created resource, if
| there is none yet? The client has nothing to request to discover
| the resource structure and associations.
|
| Also hypertext does not map well to JSON. In JSON you can not
| differenciate between data and metadata (i.e. links to other
| resources). To accomodate, you need to wrap or nest the real data
| to make side-room for metadata. Then you get ugly and hard to
| work with JSON responses. It maps pretty good to XML (i.e.
| metadata attributes or metadata namespace), but understandably
| nobody wants to work with XML.
|
| And the list goes on and on.
| janci wrote:
| Cont.: Because using HTTP verbs and status codes is stupid too:
|
| - the API is then tied to single "transport" protocol (it is
| application layer protocol in ISO/OSI but if you are not
| building a web browser, your application should reside one
| layer upwards) - it crosses ISO/OSI layer boundaries (exposes
| URLs in data, uses status codes for application error
| reporting, uses HTTP headers for pagination etc.)
|
| I think the second issue is vastly underrated. Protocols that
| cross layer boundaries are source of trouble and require tons
| of workarounds. Do you remember how FTP does not work well with
| NATs? It's because it exposes IPs and ports - transport layer
| concepts on application layer. SIP? The same thing.
|
| With true REST you can build only HTTP APIs, no websockets, no
| CLIs, no native libraries.
| derefr wrote:
| > exposes URLs in data
|
| That's, uh, the point. Without that, it's not "the web." (And
| yes, properly-structured APIs are _part of_ "the web" -- e.g.
| the first page of your paginated resource can be on one
| server, while successive pages are on some other archival
| server.) This is the whole reason for doing HATEOAS: there's
| no longer a static assumption that you're working against
| some specific server with a specific schema structure in
| place. Rather, your API client is _surfing_ the server, just
| like you 're surfing HN right now.
|
| > no websockets
|
| Correct in a nominal sense, but not in any sense 99% of
| developers would care about. Instead of RPC over websockets,
| do REST. Instead of subscriptions over websockets, do REST
| against a subscription resource for the control-plane, and
| then GET a Server-Sent Events stream for the data-plane.
| Perfectly HATEOAS compliant -- nobody ever said resource-
| representations have to be finite.
| janci wrote:
| > This is the whole reason for doing HATEOAS.
|
| Seems like a premature optimization to me. Building all
| applications so that they potentially could be distributed
| over multiple servers. YAGNI.
| zach_garwood wrote:
| Hello, this is the internet, have you heard of us?
| zozbot234 wrote:
| > On the other hand, it does not provide means to describe
| semantics of the resource properties
|
| Yup, wouldn't it be nice to have some sort of standardized
| framework to describe those resources? You could perhaps call
| it a Resource Description Framework, or RDF if you like
| acronyms.
| janci wrote:
| Aaaand we are back to XML. I don't think XML or RDF is
| particulary bad for APIs, but they are overly complex and
| that makes them unpopular.
| mdaniel wrote:
| FWIW, JSON-LD allows one to avoid XML but still gain the
| benefits of RDF, but I hear you about the "complex" part so
| ultimately it's like the other commenters have said: is it
| solving a problem your API and userbase has or not?
| zozbot234 wrote:
| How is RDF (sans XML) overly "complex"? Much of it falls
| out quite naturally from the choice of building data
| interchange on hyperlinks to resources, similar to human-
| readable hypertext.
| mdaniel wrote:
| Sorry, I didn't mean that I personally find it complex,
| merely that I've worked in enough "wwwaaah, software is
| hard, right-click-y, push" organizations to _appreciate_
| why GP would use the word complex and would find friction
| in rolling out a sane data structure
|
| The only leverage I've ever found for using good data
| structures is when I can demonstrate they solve a "today"
| pain point, because money/management DGAF about tomorrow
| anything, and only the tinyest fuck about customer pain
| so long as the checks clear
| zozbot234 wrote:
| RDF does not depend on XML. You can use JSON-LD or text-
| based syntax (N3, TURTLE or extensions thereof) and those
| are preferred in modern applications.
| wwweston wrote:
| > no sane client will go around and request random server-
| provided urls to discover what is available.
|
| "Random" isn't what's supposed to happen. You hit a top level
| endpoint, and then at that point other endpoints are made
| manifest, and then the UA/client and the user decide together
| what the next relevant endpoint is.
|
| And this is what happens all the time with the most common
| client (the browser). Seems to have worked more or less for 30
| years.
|
| As for what semantics the UA/client is capable of exploring and
| providing assistance with: who knows what's possible with
| additional heuristics + machine learning techniques?
|
| > Also hypertext does not map well to JSON... It maps pretty
| good to XML... understandably nobody wants to work with XML.
|
| I don't understand that, actually. Markup is underrated for
| data exchange potential these days. JSON is frequently (though
| not always) somewhat lighter on bandwidth and often briefer to
| type for the same underlying reasons, but beyond that there's
| no inherent advantage. It just became the easiest
| serialization/deserialization story, half out of riding the way
| that JS won, half out of what it didn't bother to try doing (a
| lot of the meta/semantics) and so gave devs permission to stop
| thinking about.
| janci wrote:
| > You hit a top level endpoint, and then at that point other
| endpoints are made manifest, and then the UA/client and the
| user decide together what the next relevant endpoint is.
|
| That's not how APIs are used. APIs consume and provide data.
| Raw data is unsuitable to be presented to the user. That's
| why HTML has so many formatting options. Formatting
| information is completely missing from APIs.
|
| > Seems to have worked more or less for 30 years.
|
| Yes, worked for good old web. In this sense, true REST is
| nothing new and even seems backwards. If we try to do REST
| while keeping data and presentation separate, we will come to
| something very similar to XML for data + XSLT for formatting.
| Or XForms. Old ideas all over again.
|
| > I don't understand that, actually. Markup is underrated for
| data exchange potential these days.
|
| XML/markup does not map well to basic data types in current
| programming languages. These work with strings, ints, floats
| and arrays/dictionaries thereof. Not Nodes, Elements and
| attributes of unknown/variant data types.
| wvenable wrote:
| > And this is what happens all the time with the most common
| client (the browser).
|
| Right. Any technology that works this way is basically a
| "browser". You could create a new markup language or data
| format and a new user agent to consume it. But you'd be re-
| inventing the wheel.
|
| There may be some use case for that, as opposed to software
| clients consuming a well defined API, but I haven't seen it
| yet. The HTML web browser basically depreciated all other
| browser-like Internet technologies when it came out (remember
| Gopher) and is even replacing actual desktop software
| clients. There's no market for alternative hypermedia clients
| so why are we giving this so much thought.
| derefr wrote:
| > but no sane client will go around and request random server-
| provided urls to discover what is available
|
| Compare and contrast: what SQL admin GUI clients do to discover
| the DBMS schema. They essentially _spider_ it.
|
| > Under HATEOAS the client would need to associate the
| knowledge of resource structure with a particular resource
| received. A promising identifier for this association would be
| the resource collection path, i.e. the URL. If the client needs
| to know the URLs, why have them in the response?
|
| The client does not need to know the URL; the client needs to
| know _how to get to_ the URL.
|
| Have you ever written a web scraper, for a site that doesn't
| really enjoy being scraped, and so uses stuff like CSRF
| protection "synchronizer tokens"? To do/get anything on such a
| site, you can't just directly go to the thing; you have to
| start where a real browser would start, and click links /
| submit forms like a browser would do, to get there.
|
| HATEOAS is the idea that APIs should also work that way:
| "clicking links" and "submitting forms" from some well-known
| root resource to get to the API you know about.
|
| As with a scraper, it's the "link text" or the "form field
| names" -- the delivered API -- that you're assuming to be
| stable; not the URL structure.
|
| > Other problems include creating new resource - how the client
| is supposed to know the structure of to-be created resource, if
| there is none yet? The client has nothing to request to
| discover the resource structure and associations.
|
| What do you think HTML forms are, if not descriptions of
| resource templates? When you GET /foos, why do you think the
| browser result is a form? It's a description of how to make a
| foo (and, through the submit attribute, a place to send it to
| get it made.)
|
| Alternately, compare/contrast what Kubernetes does -- exposes
| its resource schemas _as_ documents, living in the same
| resource-hierarchy as the documents themselves live.
|
| > Also hypertext does not map well to JSON. In JSON you can not
| differenciate between data and metadata (i.e. links to other
| resources)
|
| It's right in the name: in HATEOAS, _hypertext_ is the engine
| of application state. Hypertext as in, say, HTML. JSON is not
| hypertext, because it 's not _text_ -- it 's not a markup
| language like SGML/XML/HTML are.
|
| You realize that HTML is machine-readable, right? That you can
| respond to an XHR with HTML, and then parse it using the
| browser (or API client's) HTML parsing capabilities, just like
| you can receive and parse JSON? That there's nothing stopping
| you from using a <table> to send tabular data, etc.? And that
| if you do so, then debugging your API becomes as simple as just
| visiting the same link the API client is visiting, and seeing
| the data rendered _as HTML_ in your browser?
| janci wrote:
| I'm not sure if you are agreeing with me or disagreeing. I
| was answering the original question - why has REST become
| non-REST: it is not suitable for client-server apps.
|
| >Compare and contrast: what SQL admin GUI clients do to
| discover the DBMS schema. They essentially spider it.
|
| Not really, there is information_shema where they get
| everything they need to know about structure separately from
| data.
|
| > Have you ever written a web scraper, for a site that
| doesn't really enjoy being scraped, and so uses stuff like
| CSRF protection "synchronizer tokens"?
|
| Yes. Awful. Do we want all APIs to be like that? Why?
|
| > It's right in the name: in HATEOAS, hypertext is the engine
| of application state. Hypertext as in, say, HTML.
|
| Fully agree on this one. Just that HTML is unsuitable for
| machine-to-machine communication, so it is not used for APIs.
| Apreche wrote:
| If an API is truly RESTful does that automatically mean it's a
| high quality API? Does that mean it is functional, performant,
| reliable, secure, and generally well designed? No. An API can be
| RESTful and also trash. An API can also be non-REST and be
| amazing.
|
| Is the author correct in that APIs are inaccurately calling
| themselves RESTful? Yes, yes they are very correct.
| Congratulations. Here's a trophy for being correct. Now let's
| focus on what matters, and that is building software that works
| and works well, REST or not.
|
| Please dump the pedantry and focus on practicality.
| fabian2k wrote:
| The term is used wrong most of the time now, if you try to be
| more precise you're likely to confuse people not aware of the
| original meaning of REST. And there's not a really nice term for
| JSON-based web API that is as short as REST.
|
| Many web APIs are not REST, but still take at least a tiny bit of
| inspiration from it. Mostly the resource-based structure, not so
| much any of the other stuff like HATOAS. In practice the self-
| describing nature simply isn't useful enough, so most people
| don't bother.
| bilsbie wrote:
| You either die a hero or live long enough to become the villain.
| jayd16 wrote:
| Here's the crux of the argument but it falls flat IMO:
|
| >A proper hypermedia client that receives this response does not
| know what a bank account is, what a balance is, etc. It simply
| knows how to render a hypermedia, HTML.
|
| No true client would know how to display json or not know how to
| display html. So if you have a browser plugin that pretty prints
| json, it's RESTful? Seems pretty specious.
| lmm wrote:
| Two simple factors: 1) We needed a word for using JSON and HTTP
| statuses instead of treating HTTP as a "transport" for opaque
| SOAP payloads 2) Actual "REST" (i.e. HATEOS) is utterly useless
| and has never been successfuly implemented (except to the extent
| that the web itself qualifies), so the word was going free.
| benjiweber wrote:
| Semantic Diffusion comes for everything. See also everyone
| calling the thing they use to avoid integration "CI".
| xbar wrote:
| Even for the term Semantic Diffusion.
| dijit wrote:
| Responding to the topic: Similar to how Agile isn't very Agile, I
| suspect.
| haroldp wrote:
| Por que no los dos? You can build a "real" restful API by
| returning HTML or JSON based on the request's suffix or HTTP-
| Accept value. Hit it with a web browser and get a nice "home
| page" that says, "This is my very cool API. Here are links to
| various endpoints. Make your requests with 'Accept:
| application/json' header, or end the request path in '.json' to
| get a JSON response". Delightfully discoverable and self-
| documenting.
| twoodfin wrote:
| This article does a disservice to the benefits of "Richardson
| Maturity Level 2" i.e. "Use REST verbs".
|
| A standard set of methods--with agreed upon semantics--is a huge
| architectural advantage over arbitrary "kingdom of nouns" RPC.
|
| I'd argue that by the time your API is consistently using URLs
| for all resources and HTTP verbs correctly for all methods to
| manipulate those resources, you've achieved tremendous gains over
| an RPC model even without HATEOAS.
| weeksie wrote:
| The usefulness of metadata in rest responses ended up not
| mattering as much as people thought in most cases. Pagination is
| the best counter example but many rest apis do return next/prev
| links in the payload or in the headers. It's still REST but the
| parts that mattered (http verbs for semantic info, etc) stayed
| around.
| greenthrow wrote:
| We all decided to keep the important principles of REST and drop
| the HTML responses because HTML is a terrible format for data
| exchange between automated systems. JSON is much better for this
| because it has a simpler schema.
|
| This post is very pedantic. Being pedantic is not helpful.
| mixmastamyk wrote:
| It starts describing how we got here. While if one reads to the
| end says, "it's fine."
| shadowgovt wrote:
| The hidden cost of using hypermedia in REST has always been that
| hypermedia is machine-hostile. It has been for years.
|
| So a format intended for machine-to-machine communication is
| taking on huge cost adopting a full hypermedia format for its
| output. Ignoring the initial question of "What version of
| hypermedia" (i.e. are we doing full modern HTML? Can I embed
| JavaScript in this response and expect the client to interpret
| it?), that's just overkill when 99% of the time the client and
| the server both understand the format of the data and don't need
| the supporting infrastructure a full hypermedia REST
| implementation provides.
|
| For the same reasons XML-RPC more-or-less lost the fight, HTML
| (as a not-very-lightweight subset of XML) was going to lose the
| fight.
|
| That having been said, there are some great ideas from the REST
| approach that can make a lot of sense with a JSON payload (such
| as standardizing on URLs as the way foreign resources are
| accessed, so your client doesn't have to interpret different
| references to other resources in different ways). But using HTML-
| on-the-wire isn't generally one of them; it's a solution looking
| for a problem that brings a full flotilla of problems with it.
| a4isms wrote:
| As an "elder" in our industry, I encounter "old people arguments"
| on a regular basis. A few observations that seem to apply here:
|
| 1. Naming things is hard. Sometimes a thing gets a name for a
| reason that made sense a long time ago, but things evolve, and
| the original name no longer makes sense.
|
| This isn't necessarily a problem. Nobody cares that we no longer
| typeset words and print images on paper, physically cut them out,
| and then physically paste them onto a board, which we take a
| picture of and use the picture to run the phototypesetter
| (https://en.wikipedia.org/wiki/Phototypesetting).
|
| Yes, I am old enough to have worked on hybrid publishing system
| that used laser printers to create text that was physically
| copied and pasted in the manner described above. No, I don't
| argue that "cut" and "paste" are the wrong words to describe what
| happens in editing software.
|
| So if we use the term "REST" today in a manner that doesn't agree
| with how the coiner of the term meant it when discussing the
| architecture of a distributed hypermedia system... Sure, why not,
| that's ok. We also don't use terms like "OOP" or "FP" precisely
| the way the terms were used when they were first coined, and for
| that matter, we probably don't all agree on exactly what they
| mean, but we agree enough that they're useful terms.
|
| What else matters? Well...
|
| 2. Sometimes arguing about what the words used to mean is a proxy
| for arguing about the fact that what we consider good design has
| changed, and some people feel it may not be for the better.
|
| That's always a valuable conversation to have. We sometimes do
| "throw out the baby with the bathwater," and drop ideas that had
| merit. We footgun ourselves for a while, and then somebody
| rediscovers the old idea.
|
| The original OOP term was about hiding internal state, yes, and
| about co-locating state with the operations upon that state, yes,
| but it was also about message-passing, and for a long time we
| practiced OOP with method calling and not message-passing, and
| sure enough, we had to rediscover that idea in Erlang and then
| Elixir.
|
| Forget whether the things we do with JSON should or shouldn't be
| called "REST-ful" because they aren't the same was what the word
| was intended to describe way back when. Good questions to ask
| are, "What did that original definition include that isn't
| present now?" "Woudl our designs be better if we behaved more
| like that original definition?" "What problems did the original
| definition address?" "Do we still have those problems, and if so,
| are they unsolved by our current practices?"
|
| If there's something good that we've dropped, maybe we will get a
| lot of value out of figuring out what it is. And if we want to
| bring it back, it probably won't be by exactly replicating the
| original design, maybe we will develop entirely new ways to solve
| the old problems that match the technology we have today.
|
| TL;DR
|
| The question of whether an old term still applies or not can
| generate a lot of debate, but little of it is productive.
|
| The question of whether an old design addressed problems that we
| no longer solve, but could solve if we recognized the problems
| and set about solving them with our current technology is always
| interesting.
| munk-a wrote:
| The short answer is... the web moved in a different way than
| expected and the useful portions of rest were preserved while
| other portions were jettisoned (the biggest one IMO isn't the
| hypertext portion (JSONs fine, it's _fine_ ) but the self-
| discoverable portion - I haven't seen a self-discoverable REST
| API _ever_ in the wild).
|
| Unfortunately the name REST was too awesome sounding and short -
| so we've never had a fork with a different name that has
| proclaimed itself as something more accurate.
|
| I don't think this is awful, FYI - it's sort of the evolution of
| tech... the OG REST wouldn't have ever gotten popular due to how
| stringent it was and I can use "That it's RESTful enough." to
| reject bad code practices without anyone being able to call me
| out on it because nobody actually remembers what REST was
| supposed to be.
|
| I'd also add - what precisely is self-descriptive HTML? All
| descriptions need reference points and nothing will be
| universally comprehensible - let alone to a machine... expecting
| a machine to understand what "Insert tendies for stonks." on an
| endpoint is unreasonable.
| coffee_beqn wrote:
| > a self-discoverable REST API
|
| I've been writing web services for over a decade and this just
| seems like a cute idea that is actually almost never at all
| useful in the real world.
| kareemsabri wrote:
| Yep, there's a big gap between what's useful in Ph.D
| dissertations and what's useful in the business of software.
| dylan604 wrote:
| >(JSONs fine, it's fine)
|
| I read this like you're convincing yourself vs the reader.
| mdaniel wrote:
| > I haven't seen a self-discoverable REST API ever in the wild
|
| I'm super cognizant this entire discussion hinges upon
| semantics, nuance, etc but the Okta API isn't terrible about
| that
|
| https://developer.okta.com/docs/reference/core-okta-api/#hyp...
|
| I haven't personally tried `curl
| https://${yourOktaDomain}/api/v1` to see what the bootstrapping
| process looks like, but I can attest they do return _links in a
| bunch of their resource responses, and I believe their own SDK
| uses them, so they're not just lip service
| masklinn wrote:
| > the useful portions of rest were preserved while other
| portions were jettisoned
|
| Not even remotely. All portions of rest were jettisoned, and
| the nice branding got slapped on familiar rpc.
|
| Fielding's rest was never about http-specific concepts, not the
| verbs, not the status code, and not cute-looking URLs.
| kareemsabri wrote:
| I don't think that's true, unless I just don't understand
| REST at all. Most "RESTful APIs" in the wild I encounter /
| implement are
|
| - stateless - cacheable - follow client-server architecture -
| support resource identification in requests - _loosely_
| support resource manipulation through representation (with
| some caveats)
|
| I don't see how it's RPC by any but the most broad
| interpretation (a function executes at another address
| space).
| jakear wrote:
| GitHub's REST api is pretty self discoverable fwiw. It kinda
| sucks honestly - every request yields pages of response with
| field after field of totally irrelevant links. Totally
| unparseable without json formatting and collapsing support, so
| CURL/wget/etc. via the terminal are painful. See for example
| the example response for getting an issue:
| https://docs.github.com/en/rest/issues/issues#get-an-issue
|
| And that even has omitted some fields you'd get back querying
| manually.
| ineptech wrote:
| I regularly interview devs and ask, "What makes a RESTful API
| RESTful?" and have never heard anyone mention hypertext or
| hypermedia. A typical answer is: stateless, uses HTTP and HTTP
| verbs, and (if the person is over 40) easier to read than SOAP.
|
| Related, it seems like "API" is quickly becoming synonymous with
| "web service API". In my experience, the thing that goes between
| two classes is almost always referred to as an "interface" only.
| maxrev17 wrote:
| But but but they mentioned hypertext in http..
| kornork wrote:
| It used to be one of my favorite pet peeves when folks would
| put "expert at RESTful APIs" on their resumes.
|
| In interviews, I would ask, "What makes an API RESTful?" and
| wait gleefully for them to stutter and stumble towards an
| answer.
|
| I would accept any kind of answer, and it was only really a
| mark against you if you couldn't dredge up something about
| "resources" or "HTTP verbs," or even just express some kind of
| awareness that there were other kinds of API.
|
| It wasn't unusual for someone to just have no clue.
|
| Maybe that makes me a grammar nazi or a*, and maybe adding that
| was just a way for kids with one internship under their belt to
| pad their experience, but I always felt like you should know
| the words on your resume.
|
| I guess now that I know about this "hypermedia" requirement, I
| should be a little more forgiving?
| dvt wrote:
| This post tries to clarify things, but it's extremely confused
| and kinda' wrong. First, REST is a type of (distributed)
| architecture and really has nothing to do with how data is sent
| over the wire (as long as it's "hypermedia"). The claim that
| RESTful state _has_ to be transferred via HTML is plain wrong[1].
|
| Second, a JSON response is simply that: a bunch of data in JSON
| format. It is _not_ JSON-RPC. JSON-RPC, unlike REST, is a
| _protocol_ -- a way a client talks to a server -- and it usually
| looks like this: --> {"jsonrpc": "2.0",
| "method": "subtract", "params": [42, 23], "id": 1} <--
| {"jsonrpc": "2.0", "result": 19, "id": 1} --> {"jsonrpc":
| "2.0", "method": "subtract", "params": [23, 42], "id": 2}
| <-- {"jsonrpc": "2.0", "result": -19, "id": 2}
|
| XML-RPC is the same thing, but done with XML instead of JSON.
|
| > The entire networking model of the application moved over to
| the JSON RPC style.
|
| No, it didn't. Well, actually, I don't know exactly _what_
| "networking model" means in this case. Pretty sure we're still
| using TCP/IP. But I think it means the data-layer protocol; this
| is, however, _still_ wrong. We 're actually using HTTP methods
| (also known as RESTful verbs[2]) along with a JSON data format.
| This is still quite screwed up in the grand scheme of things, but
| in different ways than the article argues.
|
| [1] According to the man himself, in fact:
| https://restfulapi.net/
|
| [2] A terribly confusing term
| cgrealy wrote:
| It's down to utility.
|
| It turns out that using JSON is easy, has good support and is
| relatively compact on the wire.
|
| It also turns out that using HTTP verbs and transferring the
| entire state of an object makes development easier.
|
| And equally, for 99% of use cases, it turns out that HATEOAS is
| nice but not necessary.
| smrtinsert wrote:
| I have no doubt the original vision of REST will eventually come
| to fruition. It will probably be "discovered" by some energetic
| entrepreneur in future and by used to incredible effect. I
| believe the rest of us are just going along with the flow and
| earning paychecks.
| ahepp wrote:
| I'm walking away from this article unable to find a really good
| reason to implement HATEOAS in an API meant to be consumed by a
| program (as Application Programming Interfaces typically are).
|
| The best I can come up with (and this is me _trying_ to like it)
| is that I guess the API is somewhat self documenting?
|
| I see benefits to resource orientation and statelessness, but why
| do people get so upset about these APIs not following HATEOAS? Is
| it just a form of pedantry, that it's not _really_ a REST API, it
| 's a sparkling JSON-RPC?
| optimuspaul wrote:
| Anarchy, it always has been. Everyone has their own ideas about
| what REST means or what Hypermedia means.
| etamponi wrote:
| REST, noun, acronym.
|
| 1. A term to indicate APIs that use HTTP as the transport
| protocol, and typically JSON as representation.
|
| 2. (archaic) A term conied in a paper from 2000, indicating a
| model that describes how the internet works.
| revskill wrote:
| JSON actually means Representation State Transfer that the
| original author wanted, that's what made JSON the same meaning as
| RESTful API !
| Joeri wrote:
| _The client knows nothing about the API end points associated
| with this data, except via URLs and hypermedia controls (links
| and forms) discoverable within the HTML itself. If the state of
| the resource changes such that the allowable actions available on
| that resource change (for example, if the account goes into
| overdraft) then the HTML response would change to show the new
| set of actions available._
|
| If the client knows nothing about the meaning of the responses,
| it cannot do anything with them but show them to a human for
| interpretation. This would suggest a restful api is not made for
| system-to-system communication, but requires human mediation at
| every step of the way, which is precisely not how api's are used.
| In short, this definition of restful api's can't be right,
| because it suggests restful interfaces aren't api's at all. Once
| a programmer adds code to parse the responses and extract
| meaningful data, treating the restful interface as an api, the
| tight coupling between client and server reappears.
| wwweston wrote:
| > If the client knows nothing about the meaning of the
| responses, it cannot do anything with them but show them to a
| human for interpretation.
|
| This is the best counterpoint in this discussion and it
| deserves a lot of reflection.
|
| But that reflection should include the realization that _this
| is what the browser does all the time_. Browsers don 't have
| any particular semantic model in their head of what any
| particular form action or hyperlink "means" in terms of domain
| logic... but they do have some semantics for broad classes of
| verbs and other interactions associated with markup-represented
| potential actions, and so they serve as an agent presenting
| these to the user who does whatever wetware does in processing
| domain semantics and logic and makes a choice.
|
| This has worked so well over the last 30 years it's been the
| biggest platform ever.
|
| We're now in territory where we're creating software that's
| almost alarmingly good at doing some semantic processing out of
| no particular structure. The idea that we're facing a dead end
| in terms of potential for clients to _automatically_ get
| anything out of a hypertext API seems pretty tenuous to me.
| marcosdumay wrote:
| The original requirement is something on the direction of
| generalizing HTTP into a protocol for transferring all kinds
| of data with a human representation interlinked.
|
| What would be very interesting, if HTML didn't evolve with
| the goal of containing all kinds of data with a human
| representation too. But now it's mostly redundant and people
| just prefer encoding things in HTML.
| zozbot234 wrote:
| > If the client knows nothing about the meaning of the
| responses, it cannot do anything with them but show them to a
| human for interpretation.
|
| The client "knows nothing about the meaning of the responses"
| only inasmuch as it intentionally abstracts away from that
| meaning _to the extent practicable for the intended
| application_. Of course, the requirements of a human looking at
| some data are not the same as those of a machine using that
| same data in some automated workflow.
|
| Linked Data standards (usable even within JSON via JSON-LD)
| have been developed to enable a "hyperlink"-focused approach to
| these concerns, so there's plenty of overlap with REST
| principles.
| recursivedoubts wrote:
| I am the author and I agree with most of what you are saying
| here, REST and HATEOAS are for humans:
|
| https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...
|
| I disagree that it isn't an API, but that's a definition
| quibble. It is probably more profitable to talk about RESTful
| _systems_ rather than RESTful APIs, since people think API ==
| machines talking.
| mercutio2 wrote:
| You don't mention Content-Type anywhere I could find in your
| post.
|
| I don't think hypermedia is only for humans.
|
| You can totally do REST for computers. You're just supposed
| to divide knowledge along Content-Type boundaries.
|
| It's true people mostly don't do this, but it works great
| when people bother to describe rich Content-Types.
| recursivedoubts wrote:
| I mention Content-Type in that I think that discussions
| around it have largely been a distraction from what I
| consider the core innovation of REST: the uniform
| interface.
|
| I recognize that many of the few people who still talk
| about REST would disagree with me on that.
| SilasX wrote:
| That feels like a pretty significant quibble. API stands for
| "application _programming_ interface". If you cannot write an
| application to programmatically interface with it, why would
| you call it an API?
|
| What you and the parent see REST as, should be called an
| HPAI: "human-poking-around interface".
| recursivedoubts wrote:
| REST is an application programming interface for RESTful
| systems, interpreted by RESTful clients (browsers).
|
| Generic Data APIs, and the clients that use them, are
| different and have different needs.
| SilasX wrote:
| >REST is an application programming interface for RESTful
| systems, interpreted by RESTful clients (browsers).
|
| No, the interpretation is done by the _human_ using the
| browser, which is what makes it not programmable against,
| violating the P in the acronym.
| recursivedoubts wrote:
| The brower, a hypermedia client, sees the links, for
| example, in the API responses and renders them for the
| human to interact with. The browser is a hypermedia
| client, working against a hypermedia API. It not
| understanding the content of the responses beyond the
| hypermedia layer is by design: that's the uniform
| interface of REST.
|
| I mean, this is quibbling over definitions.
|
| I agree entirely with your general point that REST hasn't
| worked out well as a network architecture for non-
| hypermedia clients.
| codethief wrote:
| > I disagree that it isn't an API, but that's a definition
| quibble.
|
| I don't understand: An API is an application _programming_
| interface, i.e. it is meant to be consumed by other programs.
| How does that go together with
|
| > REST and HATEOAS are for humans
|
| ?
|
| And how does that go together with the requirements of "no
| interpretation needed" and therefore "little coupling"
| between client and server that were mentioned in the article?
| Any API _must_ be interpreted by the calling application -
| i.e. the caller must know what they are calling and what
| responses they might get. Otherwise they cannot do anything
| useful with it - at least not in an automatic (
| _programmatic_ ) fashion.
|
| I really don't understand how something can be a REST _API_
| on the one hand (clear, well-documented interface; used for
| programming), and on the other hand is supposed to be "for
| humans" and devoid of "interpretation" on the client's part.
| (Leaving aside that, even if this were possible, the
| interpretation would simply be done by the very final client
| of the API: The human.)
|
| All in all, I simply fail to see how ideas like "REST is for
| humans", HATEOAS etc. are supposed to be actionable in the
| real world.
| recursivedoubts wrote:
| A concrete action I would suggest is splitting your data
| API out from your hypermedia API:
|
| https://htmx.org/essays/hypermedia-apis-vs-data-apis/
|
| Use hypermedia (and, who would have guessed I'd recommend
| this? something like htmx) to build your web application.
|
| Use GraphQL or whatever other nonRESTful technology fits
| best to build your data API.
| mattarm wrote:
| By my read of this "REST API" is a near oxymoron. It was never
| supposed to be an "API" in the sense that a program consumes
| it. It was originally described as "Representational State
| Transfer (REST) architectural style for distributed hypermedia
| systems" with a focus on describing resources in generic ways
| for consumption by hypermedia systems (not arbitrary
| programs!).
|
| I think this is most clearly described by two things Fielding
| wrote (and the original article links to):
|
| https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...
|
| https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...
| NonNefarious wrote:
| EXACTLY. Regurgitators of the HATEOAS mantra never address
| this. Instead you get statements like one in this article: "the
| HTML response "carries along" all the API information necessary
| to continue interacting with the system directly within
| itself."
|
| No, it doesn't. It's a list of URLs, which doesn't even
| indicate what operations they accept. The only thing REST
| supports, according to this philosophy, is a user manually
| traipsing through the "API" by clicking on stuff.
|
| Thanks for summing it up so succinctly; I thought maybe I was
| missing something.
| jaaron wrote:
| > "This would suggest a restful api is not made for system-to-
| system communication, but requires human mediation at every
| step of the way"
|
| Which is _exactly_ what REST was originally designed to do:
| provide an architecture for the _Internet_ (not your app or
| service) that allows for _humans_ using software clients to
| interact with services developed by programmers _other than_
| those which developed the clients. It was about an
| interoperable, diverse _Internet._
|
| If the distributed application is not developed across
| distributed organizations, particularly independent
| unassociated organizations, then the architectural style of
| REST is overkill for what you intend and you could have just
| kept using RPC the whole time.
|
| The point of the later RESTful API movement was to create
| distributed applications that leveraged the underlying
| architecture principles of the internet _within_ their smaller
| distributed application. The theory being that this made the
| application more friendly and native to the broader internet,
| which I do agree is true, but was never the original point of
| REST.
|
| That said, xcamvber [1] is right: this is me being an old
| person fighting an old person battle.
|
| [1] https://news.ycombinator.com/item?id=32143382
| mywittyname wrote:
| People took the useful ideas and tossed the rest.
|
| The whole idea of embedding links into the data that describe
| available operations was not seen as useful, because most
| _web pages already do that_. That was not a problem that
| needed to be solved.
|
| But the concept of resource-oriented architectures which
| leveraged HTTP verbs to act on data with descriptive URIs was
| extremely useful in an era when interactions with web servers
| would look something like POST /common/backend/doActMgt.pl
|
| Books like RESTful Web Services came out in 2007 and focused
| almost entirely on resource-oriented architecture. There's
| not really much mention of hypermedia in it. It's mostly
| about building API endpoints.
|
| It also referenced AWS S3 (wow, S3 is old) a lot and treated
| it as a reference implementation / proof of concept that the
| idea works and is scalable.
| forty wrote:
| Did you mean: People took the useful ideas and tossed the
| REST ? ;)
| jrochkind1 wrote:
| I would say "semantic web" is the key technology in an attempt
| to make that kind of API that _doesn 't_ need human
| intervention.
|
| My understanding of the vision is that when all your responses
| all described using (fielding original) REST API's via RDF,
| using URI identifiers anywhere -- then a client that has never
| seen a particular server can still automatically figure out
| useful things to do with it (per the end-user's commands,
| expressed to the software in configuration or execution by some
| UI), solely by understanding enough of the identifiers in use.
|
| You wouldn't need to write new software for each new API or
| server, even novel servers doing novel things would re-use a
| lot of the same identifiers, just mixing and matching them in
| different ways, and the client could still "automatically" make
| use of them.
|
| I... don't think it's worked out very well. As far as actually
| getting to that envisioned scenario. I don't think "semantic
| web" technology is likely to. I am not a fan.
|
| But I think "semantic web" and RDF is where you get when you
| try to take HATEOS/REST and deal with what you're describing:
| What do we need to standardize/formalize so the client _can_
| know something about the meaning of the response and be able to
| do something with it other than show it to a human, even for a
| novel interface? RDF, ostensibly.
|
| The fielding/HATEOS REST, and the origial vision of
| RDF/semantic web... are deeply aligned technologies, part of
| the same ideology or vision.
| vgel wrote:
| This is incorrect. There are plenty of machines that read the
| web: web scrapers, and they've fostered a diverse ecosystem of
| tools. Search engines, archival tools, ML dataset collection,
| browser extensions and more are able to work with hypertext
| because it's self-describing. A new site can pop up and Google
| can index it without knowing if it's a blog, forum, storefront,
| or some new genre of website that may be invented in 30 years.
| dgudkov wrote:
| >Search engines, archival tools, ML dataset collection,
| browser extensions and more are able to work with hypertext
| because it's self-describing
|
| They only read state but never _modify_ it. So it misses the
| whole point of _interaction_ with a web resource.
| vgel wrote:
| They can: my password manager auto-logs-in for me. Various
| tools will automatically find and click the "unsubscribe"
| link on a mailing list website. Scalper bots buy and resell
| all kinds of products by navigating web stores
| (unfortunately). etc.
|
| Yes, generally it's more dangerous to make destructive
| actions automatically on a site you don't know the
| structure of than against an API a human has considered and
| designed against. But think about it: the design of HTTP /
| REST makes that possible. If you tried to write a bot that
| downloaded random Windows apps and clicked random buttons
| to "scrape" them, you could easily click a "delete all my
| files" button in a file management app (not even
| considering malware). In a REST API, that's not really
| possible by just issuing GET requests. Google can safely
| GET any random URL on your site with no harm, unless you've
| made a serious programming error.
| NonNefarious wrote:
| Web-scraping is not an example of published-API usage.
| Invalid comparison.
| k__ wrote:
| This.
|
| I read quite much about REST and HATEOAS, and it didn't made
| any sense to me.
|
| Somehow the "magic sauce" was missing. How should a client that
| doesn't know anything about an API interpret it's meaning?
|
| I felt like an idiot. Like there was some high end algorithm or
| architecture that completely eluded me.
|
| But it the end, it probably just meant, HATEOAS is for humans.
| Sohcahtoa82 wrote:
| I wish I could upvote this 100 times.
|
| REST, in its most strict form, feels like it was designed for
| _humans_ to directly interact with. But this is exceptionally
| rare. Access will nearly always be done programmatically, at
| which point a lot of the cruft of REST is unnecessary.
| masklinn wrote:
| > REST, in its most strict form, feels like it was designed
| for humans to directly interact with.
|
| It was literally extracted from the browser's interaction
| model so... kinda?
| recursivedoubts wrote:
| I wish I could upvote this 100 times
| headbee wrote:
| I see this argument made assuming that REST service creators are
| not aware of L3 REST but the fact that it never caught on is at
| least some proof of its ill-fitness to the general problem.
| Nowadays we have many more options that do what L3 REST tries to
| do (OData, GraphQL, etc) and most APIs at least conform to L2
| REST. This is a classic case of friction between design intention
| and actual user experience: there was a push-door with a handle,
| and users aren't using the handle, they're just pushing it.
| andrewstuart wrote:
| The details of how computers talk to each other is, or really
| should be, largely irrelevant. It's silly busywork all the little
| micromanagement of interfaces and data structures.
|
| It's plumbing.
|
| Some time in the future there will be another level of the
| software revolution in which alot of those details can be left to
| the computers themselves to work out.
| cgrealy wrote:
| Probably, but right now, it's definitely not irrelevant.
|
| In fact, your plumbing analogy is more correct than you think.
| Most devs these days are connecting existing pieces together to
| make a system flow. We don't get paid to make the pieces, we
| get paid because we know how they should fit together.
| lloydatkinson wrote:
| At this point I've stopped caring about REST. It's like agile and
| scrum where everyone says they are doing it but everyone has
| their own opinion of what's correct.
|
| As long as there's an OpenAPI spec, sane API routes, and it uses
| a format that's easily consumable with a given ecosystem (so
| pretty much always JSON anyway), and it doesn't do anything dumb
| like return 200OK { error: true } then I'm happy with it. Too
| much bikeshedding.
|
| Bonus points if the API has a client library also.
| iamthepieman wrote:
| Why do so many APIs do that i.e. 200 OK - {"errorCode": 45634,
| "errorMessage": "you messed up"}
|
| Is there a reason that I'm just not aware of? a throwback to
| SOAP?
| glic3rinu wrote:
| I've always thought it might be PHP legacy of returning 200
| even on critical errors. AFAIK Slack and FB APIs work like
| that, and they are, or have been, PHP based...
| number6 wrote:
| Different layers: the call to the api was successful on the
| transport Layer, thus 200. You messed up something in the
| business logic or you asked for a resource that's not there.
| While often you will get a 404, this is wrong: the http call
| is successful. The endpoint did not vanish. You just asked
| for something the business end could not deliver. The
| Protocol is fine with your call.
| tirpen wrote:
| > While often you will get a 404, this is wrong: the http
| call is successful. The endpoint did not vanish
|
| According to RFC 7231, status code 404 means that the
| specified _resource_ wasn 't found. Not that the endpoint
| wasn't fount.
|
| "The 404 (Not Found) status code indicates that the origin
| server did not find a current representation for the target
| resource or is not willing to disclose that one exists. A
| 404 status code does not indicate whether this lack of
| representation is temporary or permanent; the 410 (Gone)
| status code is preferred over 404 if the origin server
| knows, presumably through some configurable means, that the
| condition is likely to be permanent."
|
| So replying 404 is the correct response.
|
| https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.4
| icedchai wrote:
| The problem is you can't differentiate between "resource
| not found" and "we never even got a chance to process the
| request for a resource" purely by status code. Maybe your
| upstream reverse proxy got mis-configured. Maybe DNS is
| broken.
| number6 wrote:
| But 404 is not the representation for not existing but
| for not found: if you return 404 you leave the user of
| the api wondering if he mistyped something, or the DNS
| broke, or some part of the routing went down.
|
| Maybe 204 would be a middle ground
| Marazan wrote:
| There's.... There is a whole.set of status codes for
| exactly those things!
| cgrealy wrote:
| > There's no HTTP result code for "your request was
| successful but your Smart Washing Machine is out of
| detergent", for example.
|
| That comes down to your definition of success. Yeah, the
| client successfully connected and the server read the
| request, but it was unable to process said request.
|
| To my mind, that's a 500, as in the server was not able
| to handle the request due to a circumstances beyond the
| clients control.
| AlexandrB wrote:
| When used in an API, HTTP acts mostly as a transport
| layer. There's no HTTP result code for "your request was
| successful but your Smart Washing Machine is out of
| detergent", for example.
| vsnf wrote:
| And yet your example is perilously close to 418
| Marazan wrote:
| That's a 5xx (assuming the washing machine is the server
| in this scenario)
|
| A problem on remote that may be resolved in the future
| that will allow a succesful request.
|
| You are allowed to attach info to error code responses,
| there is a body you can put the details in.
| lbriner wrote:
| @number6 is right. There are all kinds of problems when you
| use HTTP status codes to represent something that was
| correct for HTTP but failed business logic. You don't want
| a tonne of errors logged because someone has violated
| business logic but otherwise called the API correctly
| otherwise good luck finding actual errors where you screwed
| up by deleting an endpoint (actual 404) or where you
| changed the request model (400) etc.
|
| I'm sure people might disagree with that approach but it is
| very common and very reasonable.
| xwdv wrote:
| Because you made an error but you shouldn't worry everything
| will be OK.
| yesco wrote:
| The lead for a project I wasn't working on casually informed
| me they were doing this a few years ago, the reason for it
| was nothing complicated, they just hated HTTP status codes
| and believed it was easier to pretend they didn't exist.
|
| I mentioned that it was frustrating to work with APIs like
| that since a bunch of tooling relies on status codes,
| including the browser network tab but they just told me they
| didn't care. They also made a bunch of other questionable
| design decisions before leaving, so now I just take it for
| was it is, a red flag.
| Marazan wrote:
| 200 OK but actually you have an error from a pretend-REST API
| is my number one "old man yells at clouds" thing that drives
| me nuts. It is fundamentally disrespectful to the users of
| the API.
|
| Especially if you have metrics/alerts that are tracking
| status codes.
| treis wrote:
| >Especially if you have metrics/alerts that are tracking
| status codes.
|
| This is the point though. As a client I don't want to throw
| 400 errors. As a server I don't want to throw 500 errors
| nor some 400 error.
|
| As an example, if either client or server sees a spike of
| 404 errors they want to investigate. When the result of
| that investigation is "some crawler went haywire" or "a
| user is trying to access resources that don't exist" it's
| annoying. So the 200 OK with an error is an attempt to stop
| those sorts of scenarios. Of course like anything people
| take it too far but there's decent logic behind it.
| Marazan wrote:
| I as a client care about 400s because that means I fucked
| up.
|
| As a server I don't care about 400s because (within
| constraints) I don't care if my clients have fucked up.
|
| Ad a server I care about 500s as that means I've fucked
| up. As a client I care about 500s only so much as to know
| if I should give the server a break and try somewhere
| else.
|
| There is rich, important semantic meaning in the status
| codes.
| treis wrote:
| >I as a client care about 400s because that means I
| fucked up.
|
| Not necessarily. If the user enters in the wrong CC
| number and gets a 402 or 422 back then you don't really
| care.
|
| >As a server I don't care about 400s because (within
| constraints) I don't care if my clients have fucked up.
|
| Not necessarily. 404s can be caused by your application
| routing or a bad link you're generating.
|
| >Ad a server I care about 500s as that means I've fucked
| up.
|
| Not necessarily as 501 and 505 can be expected behavior
|
| >As a client I care about 500s only so much as to know if
| I should give the server a break and try somewhere else.
|
| This one is pretty safe
| mixmastamyk wrote:
| After many years and reading an insightful post by Ned
| Batchelder I realized it is folly to swallow errors in
| low level code.
|
| Keep the low-level simple, always throw errors and let
| the high level code decide what to do. It has the context
| and hopefully smarts to make the best decision.
| hasperdi wrote:
| Lots of legacy APIs, and bad practices. In the front-end for
| instance, response 200 was preferred because of easier
| handling (back in jQuery and Angular times). These days
| GraphQL still returns 200 on query error
| [deleted]
| tumetab1 wrote:
| Yes, because error handling is hard.
|
| The standard reply is that people "the industry" did not
| clearly defined if HTTP is a transport protocol, has the
| responsibility to delivery business messages, or if it's an
| application protocol, has the responsibility to define
| business messages/process. (Even I trying to make the issue
| clear I can not use good terms.)
|
| The simplest/tired dev way to do it make HTTP just a
| transport protocol which means HTTP Status Code only mean
| Transport success/errors. Failed to send request, HTTP 4XX,
| failed to received response HTTP 5XX. Application server
| catastrophic failure, HTTP 5XX.
|
| "RESTfull way" - Transport errors can be generated by client
| library, HTTP status codes. Business erros can be generated
| by client library, HTTP status and response body JSON
| content.
|
| It's mess and made worse by those pretending it's easy, not a
| mess and it's a standard.
| bazoom42 wrote:
| Bottom line: REST+HATEOAS is great for distributed hypermedia
| consumed and navigated by humans.
|
| It is just not a practical architecture for API's.
| geenat wrote:
| It may be time to re-visit this approach now that HTML5 is fully
| matured.
|
| HTML5 was only just released in 2014, and took many years to be
| fully supported by major browsers.
|
| At the time of JSON vs HTML, HTML was not yet in a standard place
| yet (XML API implementations were extremely inconsistent).
|
| Fast forward to 2022, fetching <div> and <a> is an elegant
| pattern, and probably the way to go for self documenting API in
| the future!
___________________________________________________________________
(page generated 2022-07-18 23:00 UTC)