I tried Json rpc, swagger, and json schema for a few use cases at work when we were deciding on our serialization format. The schema definition in it is really

I tried Json rpc, swagger, and json schema for a few use cases at work when we were deciding on our serialization format. The schema definition in it is really really ugly and I could barely get it to work. Also at the time (2015) the language support for that schema definition wasn't great. I also tried swagger at the time and there were quite a few things I just couldn't get it to do. If I couldn't get it to behave in a targeted research spike it was really going to be a non-starter for new employees trying to slam out features. These issues meant people would go with the losest typing or just "object" for a lot of items. One problem is that they both have the flexibility of XSD but whether a given laganguage will support that validation or do it correctly was spotty at best. We went with our own dumbed down version of GPRC called Twirp which is very very simplified. The schema language for proto3, which twirp uses, is a lot simpler to write, uses close to just native typing, and does a lot less. Doing less was actually nice because it meant less rules. I was able to implement the prototpe ruby version which someone else (thanks cyrus) put into production in under a day because there were so few rules but what it had gave us type safety. For years people really liked REST because it was "self describing via api" but it turns out no one cares, what they want is a client in the language they're using that works. They really don't care that much how the client is generated. So to me Interface Description Languages (IDLs) and a code gen step are what you want with some simple basic rules. We built a similar tool for config checking, and most of the features weren't used. But Twirp and this language removed a whole class of issues that had plagued us and caused outages for years around string vs int in configs and apis. Also, at our scale, for some services, proto or another binary format has substantial benefits. I'm not saying it matters for your service and human readable is great (we had to learn and built up tools to debug things, and kept json support in twirp exactly for the poor humans), but when you're sending a millon requests a second or so to a service, there is a noticeable cost equivalent to an engineer's salary in infra costs. But most people are not running at that scale. On the front end GQL worked better for us, it pushed the flexibility to the front end devs while we sorted out the back end over several years. The level of coupling we'd have had if we ran Twirp, Swagger, or anything else direct from front to back end would have made work 100 times harder. I was skeptical when they started but it's been a boon, and I was smart enough to let smart people be smart in an area I'm not smart in eg I stfu. Anyway TL;DR (at the end of course) there were better options for me such as Amazon's internal one, GRPC, Twirp, roll your own Proto based, and about a billion others. I'll also note the v1 spec wiki page link is broken.