I remember getting my hands on a CORBA specification back as a wide-eyed teen thinking there is this magical world of programming purity somewhere: all 1200 pages of it, IIRC (not sure what version).

And then you don't really need most of it, and one thing you need is so utterly complicated, that it is stupid (no RoI) to even bother being compliant.

And truly, less is more.

What RPC mechanisms, in your opinion, are the most ergonomic and why?

(I have been offering REST’ish and gRPC in software I write for many years now. With the REST’ish api generated from the gRPC APIs. I’m leaning towards dropping REST and only offering gRPC. Mostly because the generated clients are so ugly)

I'm not super familiar with SOAP and CORBA, but how is SOAP any more coherent than a "RESTful" API? It's basically just a bag of messages. I guess it involves a schema, but that's not more coherent imo, since you just end up with specifics for every endpoint anyways.

CORBA is less "incoherent", but I'm not sure that's actually helpful, since it's still a huge mess. You can most likely become a lot more proficient with RESTful APIs and be more productive with them, much faster than you could with CORBA. Even if CORBA is extremely well specified, and "RESTful" is based more on vibes than anything specific.

Though to be clear I'm talking about the current definition of REST APIs, not the original, which I think wasn't super useful.

Amen. Particularly ISO8601.

I mean, HTTP is an RPC protocol. It has methods and arguments and return types.

What I object to about eg xml-rpc is that it layers a second RPC protocol over HTTP so now I have two of them...

For me the battle is with people who want to waste time bikeshedding over the definition of "REST" and whether the APIs are "RESTful", with no practical advantages, and then having to steer the conversation--and their motivation--towards more useful things without alienating them. It's tiresome.

>the HATEOAS detail ends up having no practical value and creates more problems than the ones it solves.

Many server-rendered websites support REST by design: a web page with links and forms is the state transferred to client. Even in SPAs, HATEOAS APIs are great for shifting business logic and security to server, where it belongs. I have built plenty of them, it does require certain mindset, but it does make many things easier. What problems are you talking about?

Defining media types seems right to me, but what ends up happening is that you use swagger instead to define APIs and out the window goes HATEOAS, and part of the reason for this is just that defining media types is not something people do (though they should).

Basically: define a schema for your JSON, use an obvious CRUD mapping to HTTP verbs for all actions, use URI local-parts embedded in the JSON, use standard HTTP status codes, and embed more error detail in the JSON.

We should probably stop calling the thing that we call REST, REST and be done with it - it's only tangentially related to what Fielding tried to define.

I’m with you. HATEOAS is great when you have two independent (or more) enterprise teams with PMs fighting for budget.

When it’s just yours and your two pizza team, contract-first-design is totally fine. Just make sure you can version your endpoints or feature-flag new API’s so it doesn’t break your older clients.

> but the HATEOAS detail ends up having no practical value and creates more problems than the ones it solves.

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

And now everyone keeps re-inventing half of HTTP anyway. See this diagram https://raw.githubusercontent.com/for-GET/http-decision-diag... (docs https://github.com/for-GET/http-decision-diagram/tree/master...) and this: https://github.com/for-GET/know-your-http-well

HATEOAS adds lots of practical value if you care about discoverability and longevity.

>> The important difference being that I need to figure out the peculiarities of each such web API

So if they say it is Roy Fielding certified, you would not have to figure out any "peculiarities"? I'd argue that creating a typical OpenAPI style spec which sticks to standard conventions is more professional than creating a pedantically HATEOAS API. Users of your API will be confused and confusion leads to bugs.

So you enjoy being pedantic for the sake of being pedantic? I see no useful benefit either from a professional or social setting to act like this.

I don’t find this method of discovery very productive and often regardless of meeting some standard in the API the real peculiarities are in the logic of the endpoints and not the surface.

REST is pretty much impossible to adhere to for any sufficiently complex API and we should just toss it in the garbage

REST means, generally, HTTP requests with json as a result.

xml-rpc (before it transmogrified into SOAP) was pretty simple and flexible. Still exists, and there is a JSON variant now too. It's effectively what a lot of web APIs are: a way to invoke a method or function remotely.

It's always better to use GET/POST exclusively. The verb mapping was theoretical from someone who didn't have to implement. I've long ago caved to the reality of the web's limited support for most of the other verbs.

Isn't that fairly straightforward? PUT for full updates and PATCH for partial ones. Does anybody do anything different?

> HTTP/JSON API works too, but you can assume it's what they mean by REST.

This is the kind of slippery slope where pedantic nitpickers thrive. 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.

In this sense, the term "RESTful" is useful to shut down these pedantic nitpickers. It's "REST-adjacent" still, but the right answer to nitpicking is "who cares".

This. Or maybe we should call it "Rest API" in lowercase, meaning not the state transfer, but the state of mind, where developer reached satisfaction with API design and is no longer bothered with hypermedia controls, schemas etc.

I recall having to maintain an integration to some obscure SOAP API that ate and spit out XML with strict schemas and while I can't remember much about it, I think the integration broke quite easily if the other end changed their API somehow.

Assuming the / was meant to describe it as both an HTTP API and a JSON API (rather than HTTP API / JSON API) it should be JSON/HTTP, as it is JSON over HTTP, like TCP/IP or GNU/Linux :)

> it had proper standards

Lol. Have you read them?

SOAP in particular can really not be described as "proper".

It had the advantage that the API docs were always generated, and thus correct, but the most common thing is for one software stack not being able to use a service built with another stack.

The world would be lovely if we could have standard error, listing responses, and a common query syntax.

I haven't done REST apis in a while, but I came across this recently for standardizing the error response: https://www.rfc-editor.org/rfc/rfc9457.html

Do you care? From my point of view, post, put, delete, update, and patch all do the same. I would argue that if there is a difference, making the distinction in the url instead of the request method makes it easier to search code and log. And what's the correct verb anyway?

So that's an argument that there may be too many request methods, but you could also argue there aren't enough. But then standardization becomes an absolute mess.

So I say: GET or POST.

I actually had to change an API recently TO this. The request payload was getting too big, so we needed to send it via POST as a body.

> even sometimes read operations behind a POST

Even worse than that, when an API like the Pinboard API (v1) uses GET for write operations!

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

> HTTP 200 status with an error in JSON is used instead of HTTP status codes

I've seen some APIs that not only always return a 200 code, but will include a response in the JSON that itself indicates whether the HTTP request was successfully received, not whether the operation was successfully completed.

Building usable error handling with that kind of response is a real pain: there's no single identifier that indicates success/failure status, so we had to build our own lookup table of granular responses specific to each operation.

I present to you this monstrosity: https://stackoverflow.com/q/39110233

Presumably they had an existing API, and then REST became all the rage, so they remapped the endpoints and simply converted the XML to JSON. What do you do with the <tag>value</tag> construct? Map it to the name `$`!

Congratulations, we're REST now, the world is a better place for it. Off to the pub to celebrate, gents. Ugh.

I think people tend to forget these things are tools, not shackles

One uses POST and recognizes that REST doesn't have to be so prescriptive.

The part of REST to focus on here is that the response from earlier well-formed requests will include all the forms (and possibly scripts) that allow for the client to make additional well-formed requests. If the complex filters are able to be made with a resource representation or from the root index, regardless of HTTP methods used, I think it should still count as REST (granted, HATEOAS is only part of REST but I think it should be a deciding part here).

When you factor in the effects of caching by intermediate proxy servers, you may find yourself adapting any search-like method to POST regardless, or at least GET with params, but you don't always want to, or can't, put the entire formdata in params.

Plus, with the vagaries of CSRF protections, per-user rate-limiting and access restrictions, etc.,, your GET is likely to turn into a POST for anything non-trivial. I wouldn't advise trying for pure REST-ful on the merits of its purity.

POST the filter, get a response back with the query to follow up with for the individual resources.

    POST /complex
    
    value1=something
    value2=else

    201 Created
    Location https://example.com/complex/53301a34-92d3-447d-ac98-964e9a8b3989

It adds in some data expiration problems to be solved, but its reasonably RESTful.

There was a proposal[1] a while back to define a new SEARCH verb that was basically just a GET with a body for this exact purpose.

[1]: https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-meth...

If you really want this idiomatically correct, put the data in JSON or other suitable format, zip it and encode in Base64 to pass via GET as a single parameter. To hit the browser limits you will need so big query that you may hit UX constraints earlier in many cases (2048 bytes is 50+ UUIDs or 100+ polygon points etc).

Pros: the search query is a link that can be shared, the result can be cached. Cons: harder to debug, may not work in some cases due to URI length limits.

HTML FORMs are limited to www-form-encoded or multipart. The length or the queries on a GET with a FORM is limited by intermediaries that shouldn't be limiting it. But that's reality.

Do a POST of a query document/media type that returns a "Location" that contains the query resource that the server created as well as the data (or some of it) with appropriate link elements to drive the client to receive the remainder of the query.

In this case, the POST is "writing" a query resource to the server and the server is dealing with that query resource and returning the resulting information.

Soon, hopefully, QUERY will save us all. In the meantime, simply using POST is fine.

I've also seen solutions where you POST the filter config, then reference the returned filter ID in the GET request, but that often seems like overkill even if it adds some benefits.

If I never have to use SOAP again in my life, I will die a happy man.

> As long as they get most of the 400 status codes right (specifically 200, 401, 403, 429)

A client had build an API that would return 200 on broken requests. We pointed it out and asked if maybe it could return 500, to make monitoring easier. Sure thing, next version "Http 200 - 500", they just wrote 500 in the message body, return remained 200.

Some developers just do not understand http.

> So the lack of "HATEOaS" hasn't even been noticable for me.

I think HATEOAS tackles problems such as API versioning, service discovery, and state management in thin clients. API versioning is trivial to manage with sound API Management policies, and the remaining problems aren't really experienced by anyone. So you end up having to go way out of your way to benefit from HATEOAS, and you require more complexity both on clients and services.

In the end it's a solution searching for problems, and no one has those problems.

It isn't clear that HATEOS would be better. For instance:

>>Clients shouldn’t assume or hardcode paths like /users/123/posts

Is it really net better to return something like the following just so you can change the url structure.

"_links": { "posts": { "href": "/users/123/posts" }, }

I mean, so what? We've create some indirection so that the url can change (e.g. "/u/123/posts").

We still have gRPC though...

I disagree. It's a perfectly fine approach to many kinds of APIs, and people aren't "mediocre" just for using widely accepted words to describe this approach to designing HTTP APIs.

I met a DevOps guy who didn't know what "dotfiles" are.

However I'd argue people who use the term to describe it the same as everyone else is the smart one, if you want to refer to the "real" one just add "strict" or "real" in front of it.

I don't think we should dismiss people over drifting definitions and lack of "fountational knowledge".

This is more like people arguing over "proper" English, the point of language is to communicate ideas. 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. Likewise, the point of an API is to allow programs, systems, and people to interoperate. If it accomplishes that goal, it's fine and not worth fighting over.

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? My job isn't an academic paper, good enough to get the job done is going to have to be good enough.

What an incredibly bad take.