For my case, I think graphql solves to much — I think I want a straightforward request/response RPC, I don’t need graphql capabilities for fetching data according to a specific query.

This is kinda what protobuf does, but, impl wise, protobuf usually codgens a huge amount of ugly code which is not pleasant to work with (in addition to not being JSON). Not sure what’s the status with similar implementation complexity for graphql — didn’t get a chance to use it yet.

Honestly, graphql is perfectly reasonable.

Doesn’t it still violate HTTP, badly? IIRC, it returns error responses with status code 200. I thought that it sent mutations in GET requests too, but from a quick look it looks like I misremembered that (shame on me!).

Regardless, REST is best.

Yes, I believe both that JSON schema solves the problem I have, and that this solution, while technically working, is unsatisfactory. I don’t see a contradiction here: feels similar to, eg, inventing JSON while there’s already XML :)

Heh, I actually was thinking about your’s similar comment in another thread when asking, thanks for elaborating!

I think I agree with your reasoning, but somehow still come to the opposite conclusion.

First, agree that the JSON-RPC is a useless layer of abstraction. I’ve had to use it twice, and both times the value was negative. In this question, I am asking not about the jsonrpc 2.0, but about an RPC which works over HTTP, encoding payloads in JSON. I do have an RPC, rather than REST, style in mind though.

I also couldn’t agree more about the issue with build-time dependencies is worth solving. Build time deps is exactly the problem I see at my $dayjob. We have an JSON-over-HTTP RPC interface and the interface is defined “in code” – there’s a bunch of structs with #[derive(Serialize)] structs. And this leads people to thinking along the lines of “I need to use the API. The API is defined by this structs. Therefore, I must depend on the code implementing the API”. This wasn’t explicitly designed for, just a path of least resistance if you don’t define API explicitly, and your language has derives.

That being said, I think there has to be some dependency between producer and consumers? Unless you go full HATEOAS, you somehow need to know which method to call and (in a typed language, for ergonomics) which shape the resulting JSON would have. For stripe, I need to fetch https://stripe.com/docs/api/pagination/search to figure out what’s available. And, again, there is https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json.

And, if we need at least an informal doc for the API, I don’t see a lot of drawbacks in making it more formal and writing, say, literal typescript rather than free-form text, provided that the formalism is lightweight. The biggest practical obstacle there seems to be absence of such lightweight formalisms.

So, the specific “why”s for me wanting an IDL in an open decentralized ecosystem are:

• reifying “this is the boundary exposed to outside world” in some sort of the specific file, so that it is abundantly clear that, if you are changing this file, you might break API and external clients. You could do that in the “API is informally specified in code” scenario, but that requires discipline, and discipline is finite resource, running out especially quickly in larger teams.
• providing the low-friction way to document and publish promises regarding the API to the outside world. Again, with some discipline, documenting API in api.md file would work, but it seems to me that doc-comments require less effort for upkeep than separate guides.
• making sure that details about the language the implementation is written in don’t accidentally leak. Eg, APIs probably shouldn’t use integers larger than 32 bits because they won’t work in JavaScript, but, if my impl language is Rust, I might not realize that as native serialization libraries would make u64 just work. More generally, in Rust just slapping derive(Serialize) always works, and often little thought is given to the fact that the resulting JSON might be quite ugly to work with in any non-rust language (or just to look at).
• Maaaaybe generating stub clients and servers from the spec.

<3 exciting, from the cursory look, it does seem that the world is missing something like this, thanks!

An IDL is, as @fstamour says, and interface definition language. These are used to define interfaces in a way that is agnostic to the implementation language. Most ’80s object broker systems (COM, CORBA, and so on) had quite rich ones that allowed you to automatically map the abstractions that they provided into different languages. Many lightweight RPC mechanisms that evolved in the ‘90s in response to the perceived complexity of things like DCOM and CORBA also had them, though not all. As I recall, the W3C maintains one as well, for all of the DOM APIs, to provide the option for non-JavaScript languages in the browser to be able to take advantage of the same APIs (though since IE died, taking VBScript with it, and WebAssembly avoided direct access to JavaScript APIs, this hasn’t been very important).

The idea behind an IDL is to provide a language-agnostic description of an interface. If your underlying RPC mechanism uses JSON then you implicitly have two languages that you need to support: JSON for the wire transport and whatever language you use to implement the endpoints and you want to be able to translate from foo(42) to something that generates some JSON that looks a bit like { method: "foo", args: [ 42 ] } (or, hopefully, something more sensible) and have the foo that’s exposed to the implementation language’s type checker (does foo always take one argument and does it have to be an integer?).

Part of the problem with JSON here is that it doesn’t have a particularly rich set of primitive types. Everything is encoded as text, which has representations problems for binary floating point numbers, and JSON doesn’t have any mechanism for defining things like 32-bit integers other than as numbers. Worse, it can’t represent the entire range fo 64-bit integers at all.

JSON Schema lets you represent integers by defining that they must be a multiple of 1 and fixed-width integers by expressing the minimum and maximum values, but that’s a validation constraint rather than something that’s expressed in the wire format. This means that, if you’re using JSON, you actually want to get three things out of your IDL:

• A mapping into your implementation language(s).
• A projection into JSON for your wire format.
• A validator for the JSON that ensure that the values are all within the required ranges.

OpenAPI is an IDL for web services. AutoRest can generate Java, C#, Python, and TypeScript definitions from OpenAPI definitions. There are other tools that will generate the IDL from annotations in the server-side implementation.

Interface Definition Language