What is the point of having your client translate an action to some operation on a document (read or write), only to then have your server try to infer what action was intended by said document operation.
It pains me that this article doesn’t mention any of the trade offs of each suggestion (POST vs PUT vs PATCH and expandable objects, especially) or of using REST APIs generally.
I bit my fingers every time I have mapped HTTP verbs and neither return codes, to REST verbs and codes.
Also, error codes at the API level often need a remapping when used in user context, for example if the OAuth token expires, we don’t say it the same way for an action of the user (then it’s mandatory) than when displaying data passively (in which case it shouldn’t be too red because the user may not care).
HATEOAS is a generalization of how something like a website would let a client navigate resources (through hyperlinks). It requires an intelligent agent (the user) to make sense. Without HATEOAS, according to Roy Fielding, it's not real REST. Some poor misguided API designers thought this meant they should add URL indirections to their JSON responses, making everything more painful to use for those unintelligent clients (the code that is consuming the API). Don't do this.
If you must do REST at all - which should be up for debate - you should keep it simple and pragmatic. Your users will not applaud you for exhausting HTTP verbs and status codes. The designers of HTTP did not think of your API. You will likely end up adding extra information in the response body, which means I end up with two levels (status code and response) of matching your response to whatever I need to do.
If something doesn't quite fit and it looks ugly or out-of-place, that's normal, because REST wasn't conceived with APIs in mind. Don't go down the rabbit hole of attempting to do "real REST". There is no pot of gold waiting for you, just pointless debates and annoyed users.
The best APIs I've ever used or built have been, at best, REST-ish.
And generally the parts where they deviate from REST make them more usable, not less.
In particular:
> The central idea behind HATEOAS is that RESTful servers and clients shouldn’t rely on a hardcoded interface (that they agreed upon through a separate channel). Instead, the server is supposed to send the set of URIs representing possible state transitions with each response, from which the client can select the one it wants to transition to. This is exactly how web browsers work
[1] https://www.oreilly.com/library/view/restful-web-apis/978144...
I don't remember which API was that, I'll update the comment if I do.
Instead of building the logic to determine if, say, a Payment can be cancelled, based on its attributes, you simply check 'is the cancel link there'.
I find this a critical feature. Because between the backend, and various mobile clients, react, some admin, and several versions thereof, clients will implement such businesslogic wrong. Much better to make the backend responsible for communicating abilities. Because that backend has to do this anyway already.
I pointed him at HATEOAS and suggested if he wasn't familiar with it, he probably hasn't ever seen a truly RESTful API.
I don't think I convinced him that our approach is good (I'm not sure I am convinced either, but it works well enough for our purposes)
I do think I convinced him that "it doesn't correctly conform to a standard" isn't necessarily a useful critique , though. So that's a win.
http://harmful.cat-v.org/software/xml/soap/simple
I was puzzled, at the time, why the industry was cluttering HTTP in this way. Why not establish a clean protocol for this?
But people kept getting distracted by something that seemed like maybe it would solve the problem.
Dave Winer used to be a very big deal, having created crucial technologies for Apple back in the 1980s and 1990s, and he was initially horrified by JSON. This post is somewhat infamous:
http://scripting.com/2006/12/20.html#godBlessTheReinventers
"... and damn, IT'S NOT EVEN XML!"
He was very angry that anyone would try to introduce a new serialization language, other than XML.
My point is, the need for a clear a clean RPG protocol, but the industry has failed, again and again, to figure out how to do this. Over and over again, when the industry gets serious about it, they come up with something too complex and too burdensome.
Partly, the goal was often too ambitious. In particular, the idea of having a universal process for serializing an object, and then deserializing it in any language, so you can serialize an object in C# and then deserialize it in Java and the whole process is invisible to you because it happens automatically -- this turned out to be beyond the ability of the tech industry, partly because the major tech players didn't want to cooperate, but also because it is a very difficult problem.
> but it requires another API specification
This implies API-specs are part of the problem; and I think they are not.
Specs that have generators for client-libs (and sometimes even sever-stubs) are verrrrry important. They allow us to get some form of type-safety over the API barrier which greatly reduces bugs.
One big reason for me to go with REST is OpenAPIv3: it allows me to completely spec my API and generate clients-libs for sooo many languages, and server-stub for sooo many BE frameworks. This, to me, may weight up to the downsides of REST.
GraphQL is also picking up steam and has these generators.
JSON-RPC (while great in terms of less-overkill-than-REST) does not have so much of this.
It all came to a head when someone wrote an endpoint using a PATCH verb that some people were adamant should have been a PUT.
It was among the most silly nonsense I have ever been a part of and these discussions have thankfully gone to zero since we decided on only GET and POST
Is it in active use? Wikipedia page says last spec update was in 2010. No other details online. I could not find any specific implementations.
If you want a more advanced implementation with type inference for Typescript you can use this: https://github.com/shekohex/jsonrpc-ts
I'd still recommend implementing your own, my own implementation is based off the one above.
The only caveat compared to GRPC is you lose out on field validation due to it not being protobuf/and the obvious json decode overhead
Edit: if you want to know some current users of it, I believe the Ethereum protocol uses it heavily
I believe most users make use of it via an open source json-rpc python lib. You can find a few examples online if you'd like to know more.
A better perspective would be, most softwares can be viewed as a set of domain specific objects and the set of operations (verbs) that can happen to those objects. These operations may not be a single attribute update, but a more complex dynamic set of updates over a variety of business objects. If you try to model this with a REST api, it either quickly becomes chatty or you end up compromising on REST principles.
GraphQL seems to make much more sense than REST, IMO.
If you have to check the API docs anyways, I rather define custom domain specific verbs than debate whether something should be a PUT or a PATCH.
The basic reason you need binary identicality is the problem that a parser gives you an error state, by foregoing a parser you lose the ability to detect errors. And like you think you have the ability to detect those errors because you both depend on a shared library or something, and then you get hit by it anyway because you both depend on different versions of that shared library to interpret the thing. So you implement a version string or something, and that turns out to not play well with rollbacks, so the first time you roll back everything breaks... You finally solve this problem, then someone finds a way to route a Foo object to the Bar service via the Baz service, which (because Baz doesn't parse it) downgrades the version number but does not change the rest of the blob, due to library mismatches... Turns out when they do this they can get RCE in Bar service. There's just a lot of side cases. If you're not a fan of Whack-a-Mole it becomes easier to bundle all your services into one binary plus a flag, “I should operate as a Bar service,” to solve these problems once and for all.
I think you're misinterpreting "data transfer is in binary" with something like "a raw memory dump of an object in your program, without any serialisation or parsing step".
Sure, there is gRPC, but it requires another API specification (the proto files).
There I said it. HTTP Verbs constrained REST APIS are the worst thing ever. I hate them.
They introduce un-necessary complexity, un-necessary granularity and they almost always stray away from the "REST principles". To hell with "Hypermedia" stuff.
I find it such a joy to program in server rendered pages. No cognitive overhead of thinking in "REST".
But, of course, all this is only where the client and server are developed by the same person / company.
For publishing data and creating API for third party use, we have no serious, better alternative to REST.