Most RESTful APIs aren't really RESTful • Hacker News Board

Re: Most RESTful APIs aren't really RESTful

#421

Post by JackSlateur » Wed, Jul 09, 2025, 9:16 PM UTC

How does hateoas work with parameters ?

I mean .. ok, you have the bookmark uri, aka the entrypoint

From there, you get links of stuff. The client still need to "know" their identifiers but anyway

But the params of the routes .. and I am not only speaking of their type, I am also speaking of their meaning .. how would that work ?

I think it cannot, so the client code must "know" them, again via out of band mecanisms.

And at this point, the whole stuff is useless and we just use openapi

Re: Most RESTful APIs aren't really RESTful

#422

Post by dolmen » Wed, Jul 09, 2025, 9:20 PM UTC

HATEOAS might make a come back as it might be useful to expose an API to AI agents that would browse a service.

On the other hand, agents could as well understand an OpenAPI document, as the description of each path/schema can be much more verbose than HATEOAS. There is a reason why OpenAPI-style API are favored: less verbosity of payload. If cost of agents is based on their consumption/production of tokens, verbosity matters.

Re: Most RESTful APIs aren't really RESTful

#423

Post by recursivedoubts » Wed, Jul 09, 2025, 9:21 PM UTC

LegionMammal978 wrote: post #404

recursivedoubts wrote: post #402

Earlier quoted context omitted.

There is such a thing as a RESTful API, and that API must use hypertext, as is clearly laid out in Fielding's dissertation. I don't know what a RESTful UI is, but I do know what a hypertext is, how a server can return a hypertext, how a client can receive that hypertext and present it to a user to select actions from. Whether or not the API is being consumed by a script client or a browser client doesn't change the R…

> and that API must use hypertext I'd say that my web browser is not using hypertext. It is merely transforming it so that I can use the resulting hypermedia, and thereby interface with the remote host. That is, my browser isn't the one that decides how to interface with the remote host; I am. The browser implements the hypertext protocol and presents me a user interface to the remote host. Fielding might have a pecu…

From wikipedia's article on API[1]:

> An application programming interface (API) is a connection between computers or between computer programs. It is a type of software interface, offering a service to other pieces of software.[1] A document or standard that describes how to build such a connection or interface is called an API specification. A computer system that meets this standard is said to implement or expose an API. The term API may refer either to the specification or to the implementation.

The server and browser are two different computer programs. The browser understand how to make an API connection to a remote server and then take an HTML response it receives (if it gets one of that media type) and transform it into a display to present to the user, allowing the user to choose actions found in the HTML. It then understands how to take actions by the user and turn those into further API interactions with the remote system or systems.

Because the browser waits for a human to intervene and make choices (sometimes, consider redirects) doesn't make the overall system any less of a distributed one, with pieces of software integrating via APIs following a specific network architecture, namely what Fielding called REST.

Your intuition that this idea doesn't make a lot of sense for a script-client is correct:

https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...

[1] - https://en.wikipedia.org/wiki/API

Re: Most RESTful APIs aren't really RESTful

#424

Post by rplnt » Wed, Jul 09, 2025, 9:23 PM UTC

VladVladikoff wrote: post #132

the__alchemist wrote: post #99

Earlier quoted context omitted.

I use the term "HTTP API"; more general. Context, in light of your definition: In many cases labeled "REST", there will only be POST, or POST and GET, and HTTP 200 status with an error in JSON is used instead of HTTP status codes. Your definition makes sense as a weaker form of the original, but it it still too strict compared to how the term is used. "REST" = "HTTP with JSON bodies" is the most practical definition…

>HTTP 200 status with an error in JSON is used instead of HTTP status codes This is a bad approach. It prevents your frontend proxies from handling certain errors better. Such as: caching, rate limiting, or throttling abuse.

On the other hand, functional app returning http errors clouds your observability and can hide real errors. It's not always ideal for the client either. 404 specifically is bad. Do I have a wrong id, wrong address, is it actually 401/403, or is it just returned by something along the way? Code alone tells you nothing, might as well return 200 for a valid request that was correctly processed.

(devil's advocate, I use http codes :))

Re: Most RESTful APIs aren't really RESTful

#425

Post by SJC_Hacker » Wed, Jul 09, 2025, 9:28 PM UTC

Xenoamorphous wrote: post #383

majkinetor wrote: post #327

Earlier quoted context omitted.

Amen. Particularly ISO8601.

That would be solved if JSON had a native date type in ISO format.

JSON doesn’t really have data types beyond very simple ones

Re: Most RESTful APIs aren't really RESTful

#426

Post by hughw » Wed, Jul 09, 2025, 9:28 PM UTC

ivan_gammel wrote: post #300

shadowgovt wrote: post #232

Earlier quoted context omitted.

How does the UI check if certain operations are available?

It’s literally in server response: { … resource model _links: { “delete” : { “href” : “.” } } In this example you receive list of permitted operations embedded in the resource model. href=. means you can perform this operation on resource self link.

The promise of REST and HATEOAS was best realized not by building RESTful apps like say "my airline reservation app" but by building a programming system, spiritually like HTTP + HTML, in which you'd able to declaratively specify applications, of which "my airline reservation app" could be one and "my sports gambling service" could be another. So some smart person would invent a new application protocol with rich semantics as you did above, and a new type of user agent installed on desktops understands how to present them to the user, and the app on the server just assembles the resources in this rich format, directing users to their choices through the states of hte program.

So that never got done (because it's complex) and people started building apps like "my airline reservation app" but then realized to to build that domain app you don't need all the abstraction of a full REST system.

Re: Most RESTful APIs aren't really RESTful

#427

Post by fiedzia » Wed, Jul 09, 2025, 9:42 PM UTC

bornfreddy wrote: post #396

PaulHoule wrote: post #358

Earlier quoted context omitted.

SOAP, CORBA and such have a theory for everything (say authentication) It's hard to learn that theory, you have to learn a lot of it to be able to accomplish anything at all, you have to deal with build and tooling issues, but if you look closely there will be all sorts of WTFs. Developers of standards like that are always implementing things like distributed garbage collection and distributed transactions which are…

Agree with most of what you said, except about HTTP Basic auth. That is used everywhere - take a look at any random API and there is roughly 90% chance that this is the authentication mechanism used. For backends which serve a single frontend maybe not so much, but still in places.

I've found recently that CORS doesn't work with it, which kills it for a lot of usecases.

Re: Most RESTful APIs aren't really RESTful

#428

Post by ChrisMarshallNY » Wed, Jul 09, 2025, 9:48 PM UTC

Eh. I won't write "pure" REST, because it's difficult to use, and I don't know if I have ever seen a tool that uses it as such. I know why it was designed that way, but I have never needed that.

I tend to use REST-like methods to select mode (POST, GET, DELETE, PATCH, etc.), but the data is usually a simple set of URL arguments (or associated data). I don't really get too bent out of shape about ensuring the data is an XML/JSON/Whatever match for the model structure. I'll often use it coming out, but not going in.

Re: Most RESTful APIs aren't really RESTful

#429

Post by troupo » Wed, Jul 09, 2025, 10:04 PM UTC

ivan_gammel wrote: post #420

troupo wrote: post #401

Earlier quoted context omitted.

With HATEOAS you're supposed to return the list of available actions with the representation of your state. Neo4j's old REST API was really good about that. See e.g. get node: https://neo4j.com/docs/rest-docs/current/#rest-api-get-node

That API doesn’t look like REST level 3 API. For example, there’s an endpoint to create a node. It is not referenced by root or anywhere else. GetNode endpoint does include some traversal links in response, but those links are part of domain model, not part of the protocol. HAL does offer a protocol by which you enhance your domain model with links with semantics and additional resources.

I'm not saying it's perfect, but it's really good, and you could create a client for it in an evening.

Re: Most RESTful APIs aren't really RESTful

#430

Post by thaumasiotes » Wed, Jul 09, 2025, 10:13 PM UTC

Traubenfuchs wrote: post #151

thaumasiotes wrote: post #110

Earlier quoted context omitted.

What is the problem with posting to /user/signup that posting to /user:signup solves?

You might not want a dedicated „Signup“ entity in your model and db.

...so? Don't have one.