Comment by cjpearson

I've seen some systems with a lot of pieces where teams have attempted to avoid repetition and arranged to use a single source of schema truth to generate various other parts automatically, and it was generally more brittle and harder to maintain due to different parts of the pipeline owned by different teams, and operated on different schedules. Furthermore it became hard to onboard to these environments and figure out how to make changes and deploy them safely. Sometimes the repetition is really the lesser evil.

I keep pining for a stripped-down gRPC. I like the *.proto file format, and at least in principle I like the idea of using code-generation that follows a well-defined spec to build the client library. And I like making the API responsible for defining its own error codes instead of trying to reuse and overload the transport protocol's error codes and semantics. And I like eliminating the guesswork and analysis paralysis around whether parameters belong in the URL, in query parameters, or in some sort of blob payload. And I like having a well-defined spec for querying an API for its endpoints and message formats. And I like the well-defined forward and backward compatibility rules. And I like the explicit support for reusing common, standardized message formats across different specs.

But I don't like the micromanagement of field encoding formats, and I don't like the HTTP3 streaming stuff that makes it impossible to directly consume gRPC APIs from JavaScript running in the browser, and I don't like the code generators that produce unidiomatic client libraries that follow Google's awkward and idiosyncratic coding standards. It's not that I don't see their value, per se*. It's more that these kinds of features create major barriers to entry for both users and implementers. And they are there to solve problems that, as the continuing predominance of ad-hoc JSON slinging demonstrates, the vast majority of people just don't have.

Brb, I'm off to invent another language independent IDL for API definitions that is only implemented by 2 of the 5 languages you need to work with.

I'm joking, but I did actually implement essentially that internally. We start with TypeScript files as its type system is good at describing JSON. We go from there to JSON Schema for validation, and from there to the other languages we need.

It's not that we like it, it's just that most other solutions are so complex and difficult to maintain that repetition is really not that bad a thing.

I was however impressed with FastAPI, a python framework which brought together API implementation, data types and generating swagger specs in a very nice package. I still had to take care of integration tests by myself, but with pytest that's easy.

So there are some solutions that help avoid schema duplication.

My experience is that all of these layers have identical data models when a project begins, and it seems like you have a lot of boilerplate to repeat every time to describe "the same thing" in each layer.

But then, as the project evolves, you actually discover that these models have specific differences in different layers, even though they are mostly the same, and it becomes much harder to maintain them as {common model} + {differences}, than it is to just admit that they are just different related models.

For some examples of very common differences:

- different base types required for different languages (particularly SQL vs MDW vs JavaScript)

- different framework or language-specific annotations needed at different layers (public/UNIQUE/needs to start with a capital letter/@Property)

- extra attached data required at various layers (computed properties, display styles)

- object-relational mismatches

The reality is that your MDW data model is different from your Database schema and different from your UI data model (and there may be multiple layers as well in any of these). Any attempt to force them to conform to be kept automatically in sync will fail, unless you add to it all of the logic of those differences.

Having 12 different independent copies means nobody on your 30 people multi-region team is blocked.

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 invariably problematic.

Circa 2006 I was working on a site that needed to calculate sales tax and we were looking for an API that could help with that. One vendor uses SOAP which would have worked if we were running ASP.NET but we were running PHP. In two days I figured out enough to reverse engineer the authentication system (docs weren't quite enough to make something that worked) but then I had more problems to debug. A competitive vendor used a much simpler system and we had it working in 45 min -- auth is always a chokepoint because if you can't get it working 100% you get 0% of the functionality.

HTTP never had an official authentication story that made sense. According to the docs there are basic, digest, etc. Have you ever seen a site that uses them? The world quietly adopted cookie-based auth that was an ad-hoc version of JSON Web Tokens, once we got an intellectually coherent spec snake oil vendors could spam HN with posts about how bad JWT is because... It had a name and numerous specifics to complain about.

Look at various modern HTTP APIs and you see auth is all across the board. There was the time I did a "shootout" of roughly 10 visual recognition APIs, I got all of them working in 20-30 mins except for Google where I had to install a lot of software on my machine, trashed my Python, and struggled mightily because... they had a complex theory of authentication which was a barrier to doing anything at all.

Worse is better.

Just use gRPC or ConnectRPC (which is basically gRPC but over regular HTTP). It's simple and rigid.

REST is just too "floppy", there are too many ways to do things. You can transfer data as a part of the path, as query parameters, as POST fields (in multiple encodings!), as multipart forms, as streaming data, etc.

Always thought that a standard like ISO8601 which always stores the date and time in UTC but appends the local time zone would beneficial.

ISO8601 is really broad with loads of edge cases and differing versions. RFC 3339 is closer, but still with a few quirks. Not sure why we can't have one of these that actually has just one way of representing each instant.

Related: https://ijmacd.github.io/rfc3339-iso8601/

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

> He formalised a concept and gave it a snappy name, and then the concept got left behind and the name stolen away from the purpose he created it for.

I'm not sure the "name was stolen" or the zealot concept actually never got any traction in production environments due to all the problems it creates.

It was buried towards the bottom of the article, but the reason, to me:

Clients can be almost automatic with a HATEOS implementation, because it is a self describing protocol.

Of course, Open API (and perhaps to some extent now AI) also mean that clients don't need to be written they are just generated.

However it is important perhaps to remember the context here: SOAP is and was terrible, but for enterprise that needed a complex and robust RPC system, it was beginning to gain traction. HATEOS is a much more general yet simple and comprehensive system in comparison.

Of course, you don't need any of this. So people built APIs they did need that were not restfull but had an acronym that their bosses thought sounded better than SOAP, and the rest is History.

Then let developer-Darwin win and fire those people. Let the natural selection of the hiring process win against pedantic assholes. The days are too short to argue over issues that are not really issues.

Can we just call them HTTP APIs?

> (...) and part of the reason for this is just that defining media types is not something people do (...)

People do not define media types because it's useless and serves no purpose. They define endpoints that return specific resource types, and clients send requests to those endpoints expecting those resource types. When a breaking change is introduced, backend developers simply provide a new version of the API where a new endpoint is added to serve the new resource.

In theory, media types would allow the same endpoint to support multiple resource types. Services would sent specific resource types to clients if they asked for them by passing the media type in the accept header. That is all fine and dandy, except this forces endpoints to support an ever more complex content negotiation scheme that no backend framework comes close to support, and this brings absolutely no improvement in the way clients are developed.

So why bother?

complexity

> We should probably stop calling the thing that we call REST (...)

That solves no problem at all. We have Richardson maturity model that provides a crisp definition, and it's ignored. We have the concept of RESTful, which is also ignored. We have RESTless, to contrast with RESTful. Etc etc etc.

None of this discourages nitpickers. They are pedantic in one direction, and so lax in another direction.

Ultimately it's all about nitpicking.

> If you are told an api is restful there’s an expectation of how it will behave.

And today, for most people in most situations, that expectation doesn’t include anything to do with HATEOAS.

Words derive their meaning from the context in which they are (not) used, which is not fixed and often changes over time.

Few people actually use the word RESTful anymore, they talk about REST APIs, and what they mean is almost certainly very far from what Roy had in mind decades ago.

People generally do not refer to all smartphones as iPhones, but if they did, that would literally change the meaning of the word. Examples: Zipper, cellophane, escalator… all specific brands that became ordinary words.

> Only because we never had the tools and resources that, say, GraphQL has.

GraphQL promised to solve real-world problems.

What real world problems does HATEOAS addresses? None.

Discoverability by whom, exactly? Like if it's for developer humans, then good docs are better. If it's for robots, then _maybe_ there's some value... But in reality, it's not for robots.

HATEOAS solves a problem that doesn't exist in practice. Can you imagine an API provider being like, "hey, we can go ahead and change our interface...should be fine as long as our users are using proper clients that automatically discover endpoints and programmatically adapt accordingly"? Or can you imagine an API consumer going, "well, this HTTP request delivers the data we need, but let's make sure not to hit it directly -- instead, let's recursively traverse a graph of requests each time to make sure this is still the way to do it!"

For most APIs that doesn’t deliver any value which can’t be gained from API docs, so it’s hard to justify. However, these days it could be very useful if you want an AI to be able to navigate your API. But MCP has the spotlight now.

LLMs also appear to have an easier time consuming it (not surprisingly.)

op's article could've been plucked from 2012 - this is one of my favorite rest rants from 2012: https://mikehadlow.blogspot.com/2012/08/rest-epic-semantic-f...

..that was written before swagger/openAPI was a thing. now there's a real spec with real adoption and real tools and folks can let the whole rest-epic-semantic-fail be an early chapter of web devs doing what they do (like pointing at remotely relevant academic paper to justify what they're doing at work)

I can see a value in pedantry in a professional setting from a signaling point of view. It's a cheap way to tell people "Hey! I'm not like those other girls, I care about quality," without necessarily actually needing to do the hard work of building that quality in somewhere where the discerning public can actually see your work.

(This is not a claim that the original commenter doesn't do that work, of course, they probably do. Pedants are many things but usually not hypocrites. It's just a qualifier.)

You'd still probably rather work with that guy than with me, where my preferred approach is the opposite of penalty. I slap it all together and rush it out the door as fast as possible.

What some people call pedantic, others may call precision. I normally just call the not-quite-REST API styles as simply "HTTP APIs" or even "RPC-style" APIs if they use POST to retrieve data or name their routes in terms of actions (like some AWS APIs).

100%. The needs of the client rule, and REST rarely meets the challenge. When I read the title, I was like "pfff", REST is crap to start with, why do I care?

It also means they made some effort to use appropriate http verbs instead of GET/POST for everything, and they made an effort to organize their urls into patterns like `/things/:id/child/:child_id`.

It was probably an organic response to the complexity of SOAP/WSDL at the time, so people harping on how it's not HATEOAS kinda miss the historical context; people didn't want another WSDL.

> The start to complain that if you accept any media type other than JSON then it's not "REST-adjacent" anymore because JSON is in the name and some bloke wrote down somewhere that JSON was a trait of this architectural style.

wat?

Nowhere is JSON in the name of REpresentational State Transfer. Moreover, sending other representations than JSON (and/or different presentations in JSON) is not only acceptable, but is really a part of REST

I just consumed an API where errors were marked with a "success": false field.

The "success" is never true. If it's successful, it's not there. Also, a few endpoints return 500 instead, because of course they do. Oh, and one returns nothing on error and data on success, because, again, of course it does.

Anyway, if you want a clearer symptom that your development stack is shit and has way too much accidental complexity, there isn't any.

Ive seen this a few times in the past but for a different reason. What would happen in these cases was that internally there’d be some cascade of calls to microservices that all get collected. In the most egregious examples it’s just some proxy call wrapping the “real” response.

So it becomes entirely possible to get a 200 from the thing responding g to you but it may be wrapping an upstream error that gave it a 500.

I've had frontend devs ask for this, because it was "easier" to handle everything in the same then callback. They wanted me to put ANY error stuff as a payload in the response.

{ "statusCode": 200, "error" : "internal server error" }

Nice.

Yes, so the link doesn't have to be relative to the current host. If you move user posts to another server, the href changes, nothing else does.

If suddenly a bug is found that lets people iterate through users that aren't them, you can encrypt the url, but nothing else changes.

The bane of the life of backend developers is frontend developers that do dumb "URL construction" which assumes that the URL format never changes.

It's brittle and will break some time in the future.

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 :))

PUT for partial updates, yes, constantly. What i worked with last week: https://docs.gitlab.com/api/projects/#edit-a-project

That's straightforwardly 'correct' and Fielding's thesis, yes. Yes people do things differently!

Lots of people make PUTs that work like PATCHes and it drives me crazy. Same with people who use POST to retrieve information.

You sweet summer child.

Agreed... in most large (non trivial systems) REST ends up looking/devolving closer to RPC more and more and you end up just using get and post for most things and end up with a REST-ISH-RPC system in practice.

REST purists will not be happy, but that's reality.

What is the limited support for CONNECT/HEAD/OPTIONS/PUT/DELETE ?

> The client in most cases does not care about why something failed, only whether it has failed.

"...and therefore using different status codes in the responses is mostly pointless. Therefore, use 200 and put "s":"error" in the response".

> Being able to tell apart if the failure was due to reverse proxy or database or whatever is the server's concern.

One of the very common failures is for the request to simply never reach "the server". In my experience, one of the very first steps in improving the error handling quality (on the client's side) is to start distinguishing between the low-level errors of "the user has literally no connection Internet" and "the user has connected somewhere, but that thing didn't really speak the server protocol", and the high-level errors "the client has talked with the application server (using the custom application protocol and everything), and there was an error on the application server's side". Using HTTP-status codes for both low- and high-level errors makes such distinctions harder to figure out.

what is a unhealthy request? is searching for a user which was _not found_ by the server unhealthy? was the request successful? thats where different opinions exist.

I really like the idea of a type URL.

> From my point of view, post, put, delete, update, and patch all do the same.

That's how we got POST-only GraphQL.

In HTTP (and hence REST) these verbs have well-defined behaviour, including the very important things like idempotence and caching: https://github.com/for-GET/know-your-http-well/blob/master/m...

I agree. From what I have seen in corporate settings, using anything more than GET/POST takes the time to deploy the API to a different level. Using UPDATE, PATCH etc. typically involves firewall changes that may take weeks or months to get approved and deployed followed a never ending audit/re-justification process.

> Do you care?

I don't. I could deliver a diatribe on how even the common arguments for differentiating GET & POST don't hold water. HEAD is the only verb with any mild use in the base spec.

On the other hand:

> correct status codes and at least a few are used contrary to the HTTP spec

This is a bigger problem than verb choice & something I very much care about.

I work with an API that uses GET for delete :)

This has RESTful aesthetics but it is a bit unpractical if a read-only query changes state on the server, as in creating the uuid-referenced resource.

Isn't this twice as slow? If your server was far away it would double load times?

Similarly, a more recent proposal for a new QUERY verb: https://httpwg.org/http-extensions/draft-ietf-httpbis-safe-m...

You can also read Fielding’s old blog posts. He used to write about it a lot before before he stopped blogging.

> and people aren't "mediocre" just for using widely accepted words

If you work off "widely accepted words" when there is disagreeing primary literature, you are probably mediocre.

The point is lost on you though. There are REST APIs (almost none), and there are "REST APIs" - a battle cry of mediocre developers. Now go tell them their restful has nothing to do with rest. And I am now just repeating stuff said in article and in comments here.

I agree, thought it would be really really nice if a http method like GET would not modify things. :)

> This is more like people arguing over "proper" English, the point of language is to communicate ideas.

ur s0 rait, eye d0nt nnno wy ne1 b0dderz tu b3 "proppr"!!!!1!!

</sarcasm>

You are correct that communication is the point. Words do communicate a message. So too does disrespect for propriety: it communicates the message that the person who is ignorant or disrespectful of proper language is either uneducated or immature, and that in turn implies that such a person’s statements and opinions should be discounted if not ignored entirely.

Words and terms mean things. The term ‘REST’ was coined to mean something. I contend that the thing ‘REST’ originally denoted is a valuable thing to discuss, and a valuable thing to employ (I could be wrong, but how easy will it be for us to debate that if we can’t even agree on a term for the thing?).

It’s similar to the ironic use of the word ‘literally.’ The word has a useful meaning, there is already the word ‘figuratively’ which can be used to mean ‘not literally’ and a good replacement for the proper meaning of ‘literally’ doesn’t spring to mind: misusing it just decreases clarity and hinders communication.

> If my API is supposed to rely on content-type, how many different representations do I need? JSON is a given anymore, and maybe XML, but why not plain text, why not PDF?

Whether something is JSON or XML is independent of the representation — they are serialisations (or encodings) of a representation. E.g. {"type": "foo","id":1}, <foo id="1"/>, <foo><id>1</id></foo> and (foo (id 1)) all encode the same representation.

> I work for a German company and my German is not great but if I can make myself understood, that's all that's needed.

Really? What if somebody else wants to get some information to you? How do you know what to work on?