[HN Gopher] Should we rebrand REST?
___________________________________________________________________
Should we rebrand REST?
Author : bshanks
Score : 95 points
Date : 2021-05-26 05:03 UTC (17 hours ago)
(HTM) web link (kieranpotts.com)
(TXT) w3m dump (kieranpotts.com)
| vfc1 wrote:
| I don't think anyone cares, really. It's a well established name,
| people knows what it means a REST-style API. It's not perfect,
| but nothing is, it's good enough. Let's not change its name, what
| would be the benefit of it?
|
| It would only cause even more confusion for no good reason.
| incrudible wrote:
| Nitpickers do care. When they start adding HATEOAS and
| shoehorning semantics into HTTP verbs to make the API more
| RESTful, they make everything worse to use.
|
| The problem is that REST is a buzzword, so you want to keep the
| word somehow, but throw out the nonsense.
| thih9 wrote:
| > Nitpickers do care. When they start adding HATEOAS and
| shoehorning semantics into HTTP verbs to make the API more
| RESTful, they make everything worse to use.
|
| Sounds like bad work organisation or bad priorities are a
| factor too. These same people could as well make sure some
| other spec is followed to the letter; e.g. email validation
| logic from another HN submission [1].
|
| [1]: https://news.ycombinator.com/item?id=27263141
| slver wrote:
| > people knows what it means a REST-style API
|
| Oh they know what it means. They just don't agree about it.
|
| It's kinda like politics and sports. Everyone is an expert.
| Gunax wrote:
| I actually really _don 't_ think most people know what it
| means.
|
| Personally, I was on a team of over 10 devs and I am pretty
| sure none of us knew what REST _really_ meant (including me at
| the time).
|
| The author is practically correct--RESTful is so misunderstood
| that even large companies label their APIs as RESTful when they
| aren't.
| petee wrote:
| I concur most don't know what it means. Years ago I started
| reading around trying to understand it, and all I found was
| that the ones who supposedly did understand, really couldn't
| explain it clearly; and they all had different definitions.
|
| Reminds me of _" if you can't explain it simply, you don't
| understand it well enough"_
| sergioisidoro wrote:
| Rebranding misses the point, because most people who claim to
| provide a REST API are actually providing web API that completely
| misses many of the rest principles.
|
| What we need to do is retrain everyone to use the more general
| term "Web API" and reclaim the term "rest" for architecture and
| design decision discussions.
| bklaasen wrote:
| Yeah, I call these types of APIs "JSON over HTTP". More
| syllables than "RESTful API", but everyone knows what I'm
| talking about.
| goto11 wrote:
| I think HTTP API is fine. "Web" implies some form of hypertext
| or hypermedia, but this is not required in a API.
| zozbot234 wrote:
| "Web" standards include the Semantic-Web/Linked-Data stack
| for non-hypertext data, which is highly reliant on REST-like
| and HATEOAS principles.
| bborud wrote:
| HTTP API is awkward to pronounce. Why not call it Web API?
| jayd16 wrote:
| Can we just stop jerking off about what is and isn't REST and
| instead just focus on the pros and cons of any given API?
|
| RESTfulness is a useful pattern with some clear advantages. Its
| not a commandment.
| Communitivity wrote:
| "there's just far too much confusion about what REST means to
| rescue it"
|
| No, there is no confusing. REST is exactly what's in Roy
| Fielding's thesis. Anything as is derived from REST, often with
| dismal ends. RESTful, RESTlike, RESTish are weasel words designed
| to say something along the lines of 'It's REST, but with these
| additions', or 'It's REST, but with these constraints loosened',
| or a mix of both.
|
| I was there at the beginning of SOA in 2004 and SOA then was an
| amazingly useful concept that worked well. The term SOA was
| hijacked to mean so many things, often by consultants pitching
| their version of SOA enablement or training, and at a rapid pace.
| By 2009 the meaning of SOA was so buzzwordy and clouded that
| people were trying to invent new terms to refer to the original
| concept.
|
| If someone wants to create a new thing, create a new thing and
| give attribution to the shoulders you stand on (i.e., ABC is
| based on REST but is different in these ways..1,2,3).
| tomnipotent wrote:
| SOA was overloaded even in 2004, when IBM was promoting it
| heavily. In 2021, it so inclusive that even microservices fall
| under its purview.
|
| > often by consultants pitching
|
| You do realize the term originated by consultants, like many
| other terms used today (DDD, Gang of Four, Agile, anything from
| Fowler/Martin etc.). Consultants may not always be the best at
| implementing things, but I've always found that they do a great
| job of giving names and marketing repeatable business/software
| processes.
| Communitivity wrote:
| You're probably right. The Thomas Erl book came out in 2004,
| so it was popular at least a year before that.
|
| Btw, I am a consultant. As for implementing things - there
| are consultants that track toward the marketing/image side of
| the spectrum and there are those that track toward the
| shipping/substance side of the spectrum, as in all things.
|
| On naming you are spot on. Being good at naming things is
| almost a job requirement. I've been at larger companies where
| there were multiple training sessions on how to name things
| for marketing, and when to hire outside consultants to come
| up with the names. I was on one project where tech leadership
| was outspoken and stepped on some toes. They respun the
| projects concept slightly and changed the name to sidestep
| the animosity.
| fooyc wrote:
| REST is largely over-hyped as an API design. REST fundamentally
| represents data transfers. No business can be modeled purely as
| data transfers.
|
| CRUD API would be a good name.
| SahAssar wrote:
| I'm pretty sure netflix, spotify, notion, airtable, github and
| many others can be modeled as pretty pure data transfers. What
| am I missing? What internet-based service is not using data
| transfer as its base for building services on top of?
| fooyc wrote:
| Indeed you can interpret my comment like that, so I will
| rephrase it in an other way: REST represents everything as a
| resources and the creation, update, and retrieval of
| resources.
|
| Unless your business is fundamentally about storage without
| any kind of associated logic, REST will be a bad design
| choice. Why limit yourself to 4 verbs ? This is insane.
|
| Your business has more semantics than create, read, update,
| delete.
|
| Git has commit, rebase, branch, tag, revert, amend, clone,
| and so has GitHub. A good API will represent these actions as
| actions and not as a convoluted mess of resource creations or
| updates.
|
| There is an impedance mismatch between REST and most
| businesses, like there is an impedance mismatch between an
| ORM and a relational database.
| SahAssar wrote:
| I think we're talking about slightly different things. I'm
| using REST as an interface to a storage (of
| blobs/objects/whatever), just like you would SQL SELECT,
| UPDATE, INSERT, DELETE. I then add more things that listens
| to changes to that storage, so the data is sortof the API.
|
| You're talking about putting the API layer upfront so you'd
| have a REBASE verb in the same layer that we have GET/POST
| or SELECT/INSERT etc.
|
| Your example of git easily abstracts on my view since it
| already does those basic operations, but not on yours since
| you'd need a separate REBASE verb and so on as a part of
| the protocol.
|
| I think we just have different expectations of the
| protocol.
| beders wrote:
| It is not overhyped at all. It is misunderstood.
|
| If you pick an API stack, consider your users. If you build an
| API for general consumption that you want to gradually evolve
| and that should remain valid years from now, a RESTful API with
| HATEOS is a great choice.
|
| If you need to drive a UI from your API and you control that
| UI, use something that makes you more productive and can be
| easily changed on both ends quickly - without regards to
| backward compatibility.
|
| Not sure I understand:
|
| > No business can be modeled purely as data transfers.
|
| Most businesses can, unless you have a very different
| definition of what a data transfer is.
| fooyc wrote:
| Most business can in a convoluted way. But should you they?
|
| Take HN as an example. People can upvote comments. Should you
| represent the action of upvoting as a resource creation, in a
| REST way ? Or as an action ?
|
| Take Amazon, how do you represent the action of putting a
| cart item aside ? The action of paying ? The action of
| changing which card is the default one ?
| conradludgate wrote:
| > People can upvote comments. Should you represent the
| action of upvoting as a resource creation, in a REST way ?
|
| Maybe yes. Likes are a relationship between a User and a
| Post/Comment. In a standard normalised relational db model,
| they would have their own table. So `PUT /like` would add a
| Like to that table
| sseagull wrote:
| Thanks for putting it succinctly. I was going over some
| REST design principles and the "no verbs in the URL" thing
| is just really awkward and not intuitive (and something
| being non-intuitive leads to complexity in my opinion).
|
| As in your examples, people think in terms of data (noun)
| and what they want to do with it (verb). Cramming
| everything into 4-ish verbs makes it awkward.
|
| The solution given for this is usually to put the action in
| the body. But that feels like working around a limitation
| that doesn't even have to be there.
| felipellrocha wrote:
| > It is not overhyped at all. It is misunderstood.
|
| How many times have I heard that...
| scrumper wrote:
| This is interesting, and I broadly agree with Kieran's complaints
| about the quasi-REST-lite that passes for web APIs today.
|
| Sadly there's not much tooling or guidance around to try and
| encourage people to do REST properly. It's really not done well
| at migrating out of academia, as the author points out, and
| that's starting to look like a missed opportunity for industry.
| Other comments here seem to tacitly accept that (lots of "Oh
| well... is what it is.") Everyone's learned to operate within the
| status quo, but it's quite costly for API consumers to deal with
| a range of idiosyncratic APIs (and it's bad for providers too:
| trying to produce something ergonomic and consumable takes
| significant effort). Hypermedia would make a lot of that cost go
| away by making APIs inherently discoverable and eliminating all
| those unique client libraries and boilerplate.
|
| (Plug follows)
|
| To try and address that and, in the process, nudge the world
| towards building and using true hypermedia APIs, I and a couple
| friends started building https://intertron.dev - a mechanism to
| turn any web API into a proper, hypermedia REST API. Contact us
| on that page if this is a topic of interest, we'd love to talk.
| We can let you have a play with the pre-launch version too.
| jimmaswell wrote:
| I access a url with some parameters, I get a JSON object out,
| and it's documented what side effects or whatever happen. Why
| do we need more structure than that? I don't really see the
| need.
| shp0ngle wrote:
| People really misunderstand REST, at least as in the original
| thesis.
|
| The original thesis was _for the web_. It was not meant for
| microservice JSON APIs.
|
| And the web _is REST_. HTTP, built for web, is REST. The REST
| principles are integrated in HTTP protocol itself, for I think
| two decades now.
|
| The arguments "is this API RESTful" are nonsense.
|
| ...but yeah the article says the same, now that I actually read
| it.
|
| ...now, let's discuss what "agile" means. Or, maybe not.
| ncphil wrote:
| No. Just no. It was the "branding" of Agile by consulting
| companies and publishers as a product they could sell is what
| got us into the sh*t show we're now in. Same has happened with
| REST and everything else the marketers touch. No. The _last_
| thing we need is another vacuous rebranding. Unsurprisingly,
| most of the commentors here seem to get that, and are already
| calling out the b.s. when given the chance.
| wingi wrote:
| Yes, REST is simple a sub-set of HTTP. Nothing more.
| zozbot234 wrote:
| The article says otherwise, though. Using HTTP verbs properly
| is not sufficient for an API to be fully REST-based.
| francislavoie wrote:
| I've given up on REST and I build all my new APIs with JSON-RPC.
| https://www.jsonrpc.org/specification Super simple.
|
| I'm not a fan of the complexity things like gRPC introduce to
| most languages (the PHP tooling is horrible for example), and I
| really don't like the limitations of HTTP verbs and the box that
| trying to confirm to CRUD puts you in.
| guggle wrote:
| I second this (although I'd just stick with JSON-RPC 1.0). REST
| has its uses case, but alas it's now so ubiquitous that
| developers don't even think about wether they should or should
| not use it.
|
| For machine to machine communication between heterogenous
| systems, the simplicity of JSON-RPC means one can implement a
| client easily in any language. Also creating method stubs is
| trivial. The payload is still human-readable should you use it
| from the browser and it's not prone to debates and
| interpretations around the meaning of HTTP verbs. All you have
| to know is what method you want to call and with what
| arguments... something that is natural to all developers, while
| they almost always get the endpoints/resources/verbs thing
| wrong.
| kuu wrote:
| TLDR: REST != web service APIs
| cryptos wrote:
| That is exactly the point! Most people talking about "REST" are
| just talking about web service APIs or HTTP APIs, because they
| are not aware of the actual meaning. REST became a shallow
| term.
| fmakunbound wrote:
| No, it does not deserve a rebrand. It owns the ecosystem of shit
| that it brought about over the last two decades.
|
| I cannot tell you how many meetings I've sat through where
| engineers have wasted time on discussing the RESTiness of a given
| "API" call, or which verb makes the most sense.
|
| Anyway, we're only a couple of years of group think away from
| adopting something like JSON-RPC and then it's welcome back to
| 1999 for all.
| geodel wrote:
| Excellent point. It is like I said for Facebook is great for me
| in sense all folks who I have no interest in contacting are
| gathered at one place. So now I can avoid all in one simple
| way.
|
| > I cannot tell you how many meetings I've sat through where
| engineers have wasted time...
|
| We have similar REST experts who are making everyone else's
| life hell.
| [deleted]
| kag0 wrote:
| > which verb makes the most sense
|
| I think that's a valid discussion. Each method has specific
| semantics in the HTTP spec, and consumers of an API (both
| automated and human) will expect you to follow them.
|
| For example, I expect to be able to retry a PUT request without
| much concern. But if I'm not able to do that then that's a
| problem that would have been worth a discussion.
| mmcdermott wrote:
| I think the problem with REST is that these kinds of
| semantics discussions are helpful _if_ you go all in.
| Frankly, I've never seen anything more than toy apps that
| went all in. Most of the world wants JSON-RPC and is bending
| towards REST to be "correct." I suspect that giving in to RPC
| would be cleaner overall.
|
| Until we build proper RPC composition (via lightweight
| monads, I'm sure) and let that sweep the world.
| [deleted]
| shashurup wrote:
| And then another couple of hours wasted discussing encoding
| some complex query into url parameters. On the other hand it
| was a good lesson to avoid such discussions in the future using
| any feasible excuse.
| einrealist wrote:
| Well-written article. Its always fun to inspire coworkers/peers
| to actually read Fielding's dissertation and then have a proper
| discussion about what REST actually is/means. There are those who
| get it and are eager to think about the architectural side of the
| networked apps they work on/with. And then there are those who
| just want to code / get things done. I can't be angry about the
| latter ones. But thinking more about architectural implications
| would bring us forward in the long term.
|
| Whenever I use or write an OpenAPI/Swagger definition, my heart
| breaks. At least it gets work done. But that's also the reason
| why I personally still prefer good old server-side rendered HTML
| with progressive enhancement. There is so much overhead involved
| in defining some arbitrary HTTP API and then have a UI in some
| overly complex way. HTML is such a powerful tool to drive the
| client (the Browser).
| 0xbadcafebee wrote:
| > Client applications would not need to be hard-coded with any
| domain-specific knowledge of the server-side APIs they interact
| with. Instead, they would discover all the available resources
| and operations dynamically, at runtime. A client application
| developed for one hypermedia API could be easily forked and
| modified for another hypermedia-driven web service. And "smart
| clients", which are capable of consuming any hypermedia API with
| a common grammar, could become a reality.
|
| This is WSDL and WADL, basically, except there's no common
| grammar to render a usable interface. The only real thing like
| what is described is a browser.
|
| If you want a universal interface, you make a web app, and the
| browser is the universal UI. Otherwise you just make a crappy
| console app and a crappy custom protocol using a HTTP API (or if
| you hate compatibility, simplicity and convenience: gRPC).
|
| To answer the poster's question, no, we're not going to rebrand
| REST. There are tons of improperly used terms that have been
| around for ages, they do not get rebranded. You just have to make
| a new thing and give it a new name and hope that it too isn't
| misused. ("DevOps" is the most glaring example to me, but also
| add "hacker", "crypto", "web", "cloud", etc)
| dw-im-here wrote:
| We should rebrand REST to Rest to emphasize that the original
| meaning is lost and that we just use it as a shorthand for a http
| like API. When it comes to web it's best to set our standards as
| low as possible because being right doesn't seem to have any
| advantage over being wrong wrt adoption.
| Gunax wrote:
| The term really is a bit too academic to understand for a lot of
| people who are unfamiliar with API design, but comes down to
| fairly simple concepts when explained in plain language.
|
| I compare it to how monads have an ivory tower definition (the
| famous 'A monad is just a monoid in the category of
| endofunctors!') for mathematicians, but can be explained in
| practical terms much more helpfully, even if that loses some
| theory.
|
| Years ago I edited the Wikipedia page--it has always been thorny.
| The trouble is that the definition of REST is so abstract as to
| be completely meaningless to the average person reading the
| article.
|
| If you hate using your finite lifespan on something useful, read
| the talk page. You will find this same edit war playing out over
| 10+ years between the theorists ('a style of client-server
| stateless API design where resources undergo state transitions')
| and the realists who (mis-) define it as a HTTP api.
|
| Even though the theorists are correct, I think it's important to
| recognize that Wikipedia is going to be the first source of for
| literally millions of people. It would be a tragedy to not
| acknowledge that.
| Zababa wrote:
| The point about the World Wide Web being an implementation of
| REST was really interesting, and now that I think about it web
| pages are one of the few things that usually respect HATEOAS. I'm
| reminded of one article by the author of intercooler.js and htmx,
| "HATEOAS is for Humans"
| (https://intercoolerjs.org/2016/05/08/hatoeas-is-for-
| humans.h...), that made the same point but that I didn't
| understand fully when I read it.
| rualca wrote:
| It makes absolutely no sense to even suggest that REST should be
| rebranded "HTTP API" or even "hypermedia API" because REST is
| neither protocol-specific nor is "hypermedia" the only (or even
| main) design trait.
|
| It's like someone who is entirely unfamiliar with REST feels
| compelled to make bold statements about traits he doesn't fully
| grasp.
| goto11 wrote:
| It is the style of API's people commonly call REST API's which
| he suggest should be rebranded to HTTP API's. Because they are
| not really REST and don't need to be.
|
| He is not suggesting rebranding the architectural style known
| as REST.
| rualca wrote:
| > It is kind of API's people commonly call REST API's which
| he suggest should be rebranded to HTTP API's.
|
| First of all, the title of the blog post is literally "should
| we rebrand REST?"
|
| Secondly, these appeals to rebranding REST APIs is already
| telling of the author's lack of familiarity and insight into
| the topic. The concept of RPC-over-HTTP is already widely
| established, as also the age-old stopgap solutions to REST
| misnomers and incoherences and buzzword abuses which is the
| Richardson maturity model
|
| https://martinfowler.com/articles/richardsonMaturityModel.ht.
| ..
|
| I mean, look at the date that article was posted. 2010. It's
| over a decade old. This debate is not new, and is already
| solved. We know what REST is. We know that HATEOAS is a key
| part, and one that no one implements. We know that there are
| plenty of ignorant folks starving to put buzzwords on their
| CV. We know that most people end up using resource-driven
| RPC-over-HTTP with no hypermedia or discoverability. Just
| because a blogger failed to do his homework and happened to
| feel emboldened to coin new buzzwords that doesn't mean he's
| making any point at all or providing any value.
| unscaled wrote:
| The blog post explicitly mentions the Richardson Maturity
| model.
|
| He also says that even systems or designs are consciously
| trying to acheive Level 3 in the Richardson model (HATEOAS)
| such as JSON-LD with Hydra or JSON:API are still not
| RESTful in practice.
|
| This seems to be the main point of the article, but it is
| quite hidden. The idea of an app that can display and
| manipulate data on a distributed network of servers using a
| well-defined set of JSON-based content types is very
| interesting. But this is not what the vast majority of
| currently existing "REST APIs" (even those who are using a
| more hypermedia-oriented format like JSON:API or JSON-LD)
| are trying to do.
|
| I personally think it is too late to rebrand "REST". Like a
| lot of confusing names (NoSQL, Serverless, "Cloud", "
| _Java_ Script"), it is here to stay. But the main point the
| author is trying to make is that there are true Hypermedia
| API clients (which are virtually non-existent in the wild)
| and HTTP API with various concepts borrowed from the REST
| model (but are not fully RESTful themselves).
| masklinn wrote:
| > nor is "hypermedia" the only (or even main) design trait.
|
| If you take REST as what it's original author defined, then it
| absolutely is. Fielding literally has an article saying so:
| https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert...
|
| > REST APIs must be hypertext-driven
|
| If you take REST as what it's become (a worthless buzzword for
| HTTP-based APIs) then
|
| > REST is neither protocol-specific
|
| Is wrong in turn.
|
| You can't deny both. Unless you've decided to make it even more
| worthless and just a synonym for << API >> I guess.
| rualca wrote:
| > REST APIs must be hypertext-driven
|
| That's a reference to HATEOAS, but the whole point is that
| REST refers to an entire collection of design traits, where
| hypermedia is only one of them, and you cannot have REST if
| you do not meet other design requirements first, such as
| resource-driven architecture.
|
| Making REST all about HATEOAS is almost as bad as making REST
| all about hard coded paths to resources.
|
| > If you take REST as what it's become (...)
|
| REST didn't became anything. It has always been the same
| thing. It's specification is set in stone in the doctoral
| thesis, and complemented with subsequent posts and public
| statements from the author.
|
| This sort of post has nothing to do with REST at all. It has
| zero to do with technology or design. This is vacuous and
| baseless buzzword bingo that adds nothing of value and just
| manifest a fundamental misunderstanding of the subject that
| is intended to be discussed.
|
| We already have RPC-over-HTTP. It's not REST, everyone knows
| that. That's a very old concept, as is the resistance to
| implement HATEOAS. There is nothing of value in this. It's
| just a clear sign that the author jumped to the part where he
| feels compelled to coin buzzwords by appropriating
| established and well-defined concepts while skipping the part
| he gets acquainted with the subject, thus showing a
| fundamental misunderstanding of the whole topic.
| jayd16 wrote:
| >A REST API should not be dependent on any single
| communication protocol
|
| I think hypertext is wider than HTTP as far as this blog post
| in concerned.
| masklinn wrote:
| > I think hypertext is wider than HTTP as far as this blog
| post in concerned.
|
| Yes? Did you wildly misread my comment?
|
| REST is either the original definition, in which it is
| hypertext-driven and protocol-agnostic, or a worthless
| buzzword for http APIs which are not hypertext-driven but
| are very much protocol-specific.
| tuxie_ wrote:
| The author suggests that "there's just far too much confusion
| about what REST means to rescue it" and suggests differentiating
| APIs in 2 other categories instead, but in my opinion this not
| only introduces more confusion, but even there doesn't seem to be
| any constrain that would prevent the same confusion from arising
| again. There's no library to enforce a certain standard. It's
| just another set of well-intentioned guidelines.
|
| In a few years we would be reading "should we rebrand Hypermedia
| APIs?" kind of blog posts.
| slver wrote:
| > in my opinion this not only introduces more confusion
|
| I don't think that's possible. I've officially banned the word
| "REST" from being used in technical discussions. Using that
| word is not just useless, it's harmful.
|
| Note that this is not an issue with the original paper, but
| everything that happened after it.
| EMM_386 wrote:
| > I don't think that's possible. I've officially banned the
| word "REST" from being used in technical discussions.
|
| I've been a software engineer for decades and I am helping a
| company move from SOAP-based XML services into a more
| coherent REST-type architecture.
|
| Why would this be a banned technical discussion?
| deaddodo wrote:
| I think their point is that REST means nothing beyond "uses
| HTTP verbs" these days. Most companies/teams can't even
| agree on the differences between POST, PUT and PATCH; let
| alone status codes, payload structure, authentication, etc.
| So using the term REST will mean something different to
| every person using it. Similar to how a Ruby, PHP and
| Python engineer will envision a different architecture if
| you tell them to build a "backend".
| slver wrote:
| > I think their point is that REST means nothing beyond
| "uses HTTP verbs"
|
| Funny thing is that this means HTML pages also aren't
| restful, because they stick to GET and POST.
| deaddodo wrote:
| HTML (/browsers) have agreed upon payloads, status codes
| and authentication. The lack of PUT/DELETE/etc is more a
| function of use cases than the HTTP/HTML standard and
| there are plenty of example servers that are fully
| RESTful. That was also the original use case of web
| browsers (as a better/enhanced FTP).
| bewo001 wrote:
| They call REST anything that uses JSON over HTTP
| nowadays. What I don't get, when they don't know or don't
| want to do REST, why they are not just calling their API
| JSON/HTTP?
| mixmastamyk wrote:
| Say the two phrases out loud and the reason becomes
| obvious. The second doesn't exactly roll off the tongue.
| ajuc wrote:
| JSON API would be my preferred name.
| mixmastamyk wrote:
| I suppose but json is the least important part of the
| "spec."
| goto11 wrote:
| The problem is not REST per se, the problem is people
| thinking a machine-to-machine API "should" conform to REST. I
| have not seen a coherent argument for why HATEOAS should be a
| useful property for API's beside "REST says so".
|
| That said, we should not throw the baby out with the
| bathwater. Some REST principles like statelessness are good
| design for API's also.
| dragonwriter wrote:
| > I have not seen a coherent argument for why HATEOAS
| should be a useful property for API's beside "REST says
| so".
|
| Loose coupling and extensibility, the same reason that its
| used on the web, which is quite critically a machine-to-
| machine protocol (while obviously humans consume it via
| user-agents, automatic crawling and othee machine-to-
| machine processing is key to the success of the web) and
| HATEOAS is key to why it works.
| pa7x1 wrote:
| 100% agree, HATEOAS is rather useless for machine-to-
| machine. And it shouldn't come as a surprise that most APIs
| decide to not commit to this design constraint.
|
| I prefer to think of real-world APIs as coming in varying
| degees of RESTfulness depending on the design constraints
| they have chosen to conform to. Good engineering is about
| making judicious analysis of the trade-offs involved, if
| HATEOAS doesn't bring you anything dropping it is the right
| thing to do.
| einrealist wrote:
| I disagree. Even if an API is effectively used by a
| machine, the root cause either is human interaction or it
| makes sense to also allow human interaction (e.g. for
| testing, troubleshooting, interactive documentation).
| HATEOAS can help to define formats that solve both
| problems.
| slver wrote:
| You can define formats without HATEOAS.
| dragonwriter wrote:
| Obviously, since defining formats and driving logic
| through defined and identified-in-band formats is an
| element but not the whole of HATEOAS. OTOH, applications
| using pseudo-REST without HATEOAS typically hardcode both
| URLs _and_ formats rather than relying on in-band
| identification of both.
| hangonhn wrote:
| HATEOAS was a little more useful when the commonly used
| media was XML rather than JSON. XML has XPath, which I
| was able to use to find the URLs for the different
| actions I want to perform, should they ever change. In
| practice, however, those URLs never changed or were
| constructed in a very predictable way.
| Joker_vD wrote:
| HATEOAS is somewhat useful even in machine-to-machine:
| hard-coded URLs in clients are kind of a PITA to support.
| goto11 wrote:
| What is the problem with hard-coded URLs? It is certainly
| simpler than having to extract the URLs from some other
| request. If they don't change (and they shouldn't!) I
| don't see the problem.
| aaron-santos wrote:
| Harded-coded URLs represent a larger API surface area.
| Hypermedia-driven APIs eg: HATEOAS permit the server to
| view URLs as an implementation detail. Some people and
| some problems benefit from APIs with large surface area.
| Some people and problems benefit from APIs with small
| surface area.
|
| I tend to like APIs with small surface areas because it
| means I don't have to drag along outdated endpoints
| across minor versions because the org doesn't want to v2
| anything. URLs as an implementation detail makes
| backwards compatibility much easier. So many times it's
| been useful to combine or split endpoints as the business
| needs change without affecting clients.
|
| The worst part about using HATEOAS for me has been
| clients who are used to constructing URLs continue to do
| so and create a ticket where the obvious first question
| is "Are you constructing that URL?"
| PeterisP wrote:
| Even if the client fetches the URL dynamically, nothing
| about the semantics of that URL parameters or results can
| change or the client will break, you can only add extra
| optional things that the old clients will ignore. All
| those URLs still very much are part of the API surface
| area even if they're not hardcoded - their functionality
| still needs to have out-of-bounds documentation (contrary
| to the HATEOAS assumptions - "self-descriptive messages"
| IMHO can work only for syntax but are an unrealistic goal
| as far as semantics is concerned) and fixed behavior to
| match that documentation, in all realistic cases the
| client can't properly interpret the data without
| programmer intervention if the model changes.
|
| So this gives you only the freedom to change the URL
| naming scheme, but if you want to change the
| functionality in any way that's not 100% compatible, you
| still have to drag along outdated endpoints with the old
| functionality or you'll break clients.
|
| But this goes so much in contrast to your comment that it
| seems that I'm probably misunderstanding you - can you
| give an illustrative example on how exactly does this
| allow you to combine or split endpoints without affecting
| client software that sends/takes data from those
| endpoints and does some action (business logic) based on
| that data?
| Joker_vD wrote:
| And another take on why clients being able to manually
| craft URLs is bad design: [0]. But prohibitting clients
| from manually constructing URLs really is not that hard:
| [1].
|
| [1] https://blog.ploeh.dk/2013/05/01/rest-lesson-learned-
| avoid-h...
|
| [2] https://blog.ploeh.dk/2020/10/26/fit-urls/
| Joker_vD wrote:
| Well the problem is exactly that they _do_ change
| sometimes. And having only one hard-coded URL is easier
| than having twelve of those.
|
| > It is certainly simpler than having to extract the URLs
| from some other request.
|
| It's not extracted from other request, it's extracted
| from the response to the original request, and using a
| field from the local struct is not harder than using a
| global constant.
| goto11 wrote:
| > Well the problem is exactly that they do change
| sometimes.
|
| Well they shouldn't! And if the API arbitrarily changes
| URLs around without reason, then surely they might also
| change the URL for the initial request.
| Joker_vD wrote:
| > Well they shouldn't!
|
| If you treat them as public interface, they shouldn't,
| yes. But if you treat them as internal implementation
| details, they absolutely could.
|
| One can also think about it as static vs dynamic
| dispatch: you make an initial request, you get a vtable
| of "method name -> method pointer" as a part of response.
| Or you can hardcode the method pointers and make it the
| remote server's job to properly chose the appropriate
| internal endpoint.
| goto11 wrote:
| But what is the point? Why introduce an extra layer of
| complexity to mitigate changing URL's, something which
| has no purpose in the first place?
| slver wrote:
| Bingo
| PeterisP wrote:
| The practical problem I have seen with systems
| (mis?)designed like this is a scenario when the client
| needs to do action X on resource Y attached to thingy Z -
| and they already have all the required info to do that
| action - then they still need to do a request on Z to get
| the URL for Y and do a request on Y to get the url for
| action X, which adds extra requests and latency for no
| good reason. Like, there's no significant difference _if
| there is_ some original request that has been made, but
| often that "original" request is otherwise unnecessary
| and only gets made to enable that extra layer of
| indirection.
| dragonwriter wrote:
| > The practical problem I have seen with systems
| (mis?)designed like this is a scenario when the client
| needs to do action X on resource Y attached to thingy Z -
| and they already have all the required info to do that
| action - then they still need to do a request on Z to get
| the URL for Y and do a request on Y to get the url for
| action X, which adds extra requests and latency for no
| good reason.
|
| If they have "all the info they need", they have the
| identity of Y, which in a system designed around REST is
| the URL, and if Y is a resource, then its URL is the URL
| for actions on it, and the type of thing it is will tell
| you what method to use and (where one is applicable)
| resource to send to accomplish the action.
|
| HATEOAS is more than just shipping URLs.
| slver wrote:
| To be fair, you need at least one hard-coded URL in your
| client, don't you? To hit the root entrypoint.
|
| And if you have one hard-coded URL... and use it as the
| root of other URLs, then it's no hard to support than
| anything.
|
| URLs are useful in REST because the API often crosses
| domain boundaries and company boundaries. One site links
| to another and so on. Most APIs are not like that.
|
| In fact they're only like that when they serve, say,
| static image assets off a CDN, and guess what, then
| passing back a URL in your API is self-evident and
| natural.
|
| But not for everything IMHO.
| unscaled wrote:
| If you look at the hydra API example[1] linked by OP,
| this is exactly what it needs: one entrypoint URL.
|
| If your API only needs a single domain name (as over 99%
| of the APIs are), clients can just have the base URL
| encoded in a constant or a configuration file.
|
| What HATEOAS ostensibly gives you is not the ability to
| painlessly switch domains, but rather to change your
| entire URL path structure and even the entire schema
| represented by your REST endpoints.
|
| This feature turns out to be quite useless for most REST
| clients. Cosmetic changes to URL structure aside, any
| useful change (in other words - a schema change), will
| break the client logic, which is still hard-coded to deal
| with a predefined schema, predefined types of resources
| and a predefined set of actions that can be performed on
| each of them.
|
| Roy Fielding accurately notes that a truly "RESTful" app
| should let the engine of its state be completely driven
| by the server. In other words the client cannot have any
| _specific_ logic related to "state transfers".
|
| If your client is not doing this, like a browser does,
| than what does it have left to gain from implementing
| HATEOAS? I'm honestly interested in hearing good
| arguments, since I haven't heard anything that managed to
| convince me yet.
|
| I've always worked all my API up to level 2 (HTTP Verbs)
| of the Richardson Maturity model, but I've never felt
| convinced that HATEOAS is worth the effort. It seems like
| the majority of HTTP API designers out there have the
| same opinion.
|
| [1]: https://generic.hypermedia.app/
| slver wrote:
| > What HATEOAS ostensibly gives you is not the ability to
| painlessly switch domains, but rather to change your
| entire URL path structure and even the entire schema
| represented by your REST endpoints.
|
| Which would be utterly pointless, because the fact this
| schema is opaque to the clients means that it's
| meaningless to the clients.
|
| So you have no reason to change it.
|
| > I've always worked all my API up to level 2 (HTTP
| Verbs) of the Richardson Maturity model, but I've never
| felt convinced that HATEOAS is worth the effort. It seems
| like the majority of HTTP API designers out there have
| the same opinion.
|
| The "maturity model" is honestly non-sense and Fielding
| also thinks that.
|
| It's kinda like first level to being a bird is flapping
| your hands, second step is whistling with your mouth...
| No, you're not any closer to being a bird, you need to be
| the entire thing for the benefits of being a bird to come
| about.
|
| Trying to stick to the CRUD concept of HTTP verbs is
| rather harmful. CRUD is a common starting point for a
| domain's verb structure, but being restricted to it is
| crippling and results in bizarre obscure semantics or
| underdeveloped business constraints.
|
| I'd say to hell with all of it. I stick to HTTP as-is,
| and that's it. Also it's telling I think that to this day
| HTML forms only support GET and POST. Even HTML isn't
| RESTful I guess. /s
| slver wrote:
| You're entirely right.
|
| Another problem with REST is that Fielding himself
| describes it as a "large grain resource approach".
|
| It's no surprise we love HTTP and URLs when we have to
| return, say, images, downloads or entire documents in our
| APIs. Just put the URL in, serve it on your CDN.
|
| But for small grain data items, it's terrible.
| dragonwriter wrote:
| > I've officially banned the word "REST" from being used in
| technical discussions.
|
| So if I want to refer to the architecture of that name
| described in Fielding's _Architectural Styles and the Design
| of Network-based Software Architectures_ , what is the
| approved circumlocution?
| nodex-alex wrote:
| Perhaps what everyone considers is the norm is actually the norm.
|
| If the whole world decided a Rose was called a Dog then a Rose
| would be known as a Dog!
| codetrotter wrote:
| > REST is just the coolest thing in web service API design right
| now, isn't it?
|
| Is it? I still make my APIs REST-like, but I think in terms of
| "coolness", GraphQL is more appealing to people isn't it?
| Personally I reason that in my APIs GraphQL would be extra
| complexity for no benefit in my specific use-cases so far. And
| REST-like serves me well. But for me I choose this way because of
| ergonomics and because it allows me to implement the things I do
| with about the least amount of complexity. Coolness doesn't play
| a part anymore. But if it did I would surely think GraphQL would
| be more cool.
| jayd16 wrote:
| >GraphQL is more appealing to people isn't it?
|
| Its new but it has no where close to the usage of REST, I would
| imagine.
| quantified wrote:
| I wholeheartedly agree with the majority of this. In my
| experience "REST" has been like a religion in which hardly anyone
| either read the founding text or bothered to interpret very much
| of it. Fielding's thesis does not require all of what adherents
| have claimed it does. An API does not a priori need to adhere to
| any sect of "REST", though for many use cases it will benefit.
| For example, a machine-to-machine API might well have verb URLs
| to execute something. That's verboten, a sin but not an
| excommunicating taboo, in "REST". The torch carriers can get very
| specific about a great many aspects, too. I find it refreshing
| when someone makes good use of HTTP in a way that REST would
| forbid. For example, if memory serves, Elasticsearch's search API
| uses a GET verb, appropriate for retrieving, with a request body
| to provide information that would be super awkward in the URI.
| This API is not intended for UI usage, so why not do this?
|
| User interfaces can very much benefit from strategic adoption of
| application state transitions modeled via hypermedia-style links,
| that's entirely different.
|
| How likely is it, however, that even if Roy wrote an article in a
| major publication and gave talks at conferences about what's not
| really REST, the community would change its use of "RESTful"?
| h0h0h0h0111 wrote:
| >How likely is it, however, that even if Roy wrote an article
| in a major publication and gave talks at conferences about
| what's not really REST, the community would change its use of
| "RESTful"?
|
| Ha if agile is anything to go by, people on LinkedIn will be
| describing their recruiting process or marketing strategy or
| breakfast as RESTful
| bryanrasmussen wrote:
| our recruiting process is based on a set of idempotent
| responses, for example if you send in a cover letter for a
| full stack position we immediately respond with an email
| asking you to confirm that you are a rockstar ninja.
| fatnoah wrote:
| >I find it refreshing when someone makes good use of HTTP in a
| way that REST would forbid
|
| I've written many "REST" interfaces in my time and definitely
| tried to make the "right" choice vs. the dogmatically correct
| one when it made sense. I still have a copy of API
| documentation I wrote "with apologies to Roy Fielding."
| DonHopkins wrote:
| How about simply using "BEST Practices"?
|
| The trademark "YOU'VE TRIED THE REST, NOW TRY THE BEST" is
| officially abandoned, so that's available.
|
| https://trademark.trademarkia.com/youve-tried-the-rest-now-t...
| rualca wrote:
| > How about simply using "BEST Practices"?
|
| REST is already an architecture style, nothing more than an a
| set of guidelines to design interfaces in order to ensure you
| get specific qualities and operational advantages.
|
| These articles with bold statements regarding the need to
| change buzzwords already miss the whole point to begin with,
| and provide absolutely nothing of value.
| DonHopkins wrote:
| That's kind of my point. "Use BEST Practices" is nothing more
| than a set of guidelines, a bold statement to ignore the
| buzzwords and just do what is currently understood to work
| the best with today's technologies, whatever buzzwords those
| practices are currently called, which change over time.
|
| For example: BEST Practices a couple decades ago said to use
| XML over HTTP, while BEST Practices today say to use JSON
| over HTTPS.
|
| Plus, it makes you think of eating pizza, instead of
| sleeping!
|
| https://www.reddit.com/r/theouterworlds/comments/ek4gh5/pizz.
| ..
| rualca wrote:
| > That's kind of my point. "Use BEST Practices" is nothing
| more than a set of guidelines (...)
|
| I think you're missing the whole point.
|
| REST refers to a specific architecture style which
| comprises a set of very specific design criteria which are
| explicitly and very clearly specified in a doctoral
| dissertation.
|
| The term REST is a term that was coined to refer to that
| very specific set of design criteria once applied as a
| whole. Not in part, not as a cherry-picked assortment of
| choices, but as a whole.
|
| So no, the term doesn't apply to a loose set of guidelines
| which some guy decided to use just because.
|
| It would be like stating you're using HTTP just because you
| set up a protocol that does request-response and might have
| support for annotations passed as.key:value pairs
| resembling headers, buy at the same time had no verbs.
___________________________________________________________________
(page generated 2021-05-26 23:02 UTC)