oh, its not the end of the world. thinking on this is I think its that its procedural (how not what). I guess I still really like the notion of programming as unification for this kind of thing.
I'm not sure any answer other than "I felt like it was a good choice" is gonna be 100% accurate, but a few things, some of which are speculative, some of which are reactionary.
(I'm sadly not very familiar with OAS, so it's very possible that OAS supports many of the things I'm going for!)
- This takes very heavily after protos, which use a DSL.
- This rejects protos because of a few reasons, not the least of which is that every field in proto3 is optional. While it makes sense for google, I don't think it makes sense for everybody.
- gRPC is non-http, and I was unhappy with gRPC-web
- I wanted it to be a terse specification, such that just glancing over the definition file gives you a sense of what the API consists of.
- I wanted a solution that handled websockets/server push as a first-class citizen, and not as a secondary add-on
- I wanted to provide library-level validation of request / response shape.
- I wanted to extend it beyond typescript, notably into python (and hopefully beyond)
- I like the idea of generic structs and oneofs (which I'm going to implement in some future version). I think if we had an easy way to define generics in cross-language APIs, we'd probably use it a fair amount.
- I like the idea of having an extensible language, e.g. be able to provide a JSONLogic type. Imagine a field `priceCalculation: JsonLogic<string, number>`. That'd be pretty cool!
Let me preface this by saying that I use OAS because it is the most widely-supported HTTP API spec. I don't love it, but as of version 3, it handles all of my use cases and has good tooling support. This prevents me from having to edit the spec as raw text -- I can typically get by using a GUI (recently been happy with Apicurio Studio).
That said, I do wish there were a better format for it than YAML/JSON, and I think some of their design decisions were strange.
Note that a lot of OAS's strengths and weaknesses were inherited from its parent project, JSON Schema, which is also widely supported.
> I wanted it to be a terse specification, such that just glancing over the definition file gives you a sense of what the API consists of.
OAS specs in YAML (as opposed to JSON) are pretty terse and easy to scan, especially if the spec is kept fairly DRY by defining/refusing object schemas.
> I wanted a solution that handled websockets/server push as a first-class citizen, and not as a secondary add-on
OAS fails this one.[1]
> I wanted to provide library-level validation of request / response shape.
This is something all the major formats (JSON Schema/OAS, RAML, Blueprint, etc.) do. It's probably the first thing people want to do with an API spec. OAS has great support for validation in most languages, although implementation of the spec can be spottier with less-popular stacks like PHP.
> I wanted to extend it beyond typescript, notably into python (and hopefully beyond)
One of my projects uses Spot[1] to define its API. Spot has CLI tools that translate it into a plain OAS file (.yaml format), and then there are more CLI tools that generate code (models, validators, controllers, and even servers) from that spec file.
If you don't mind a polyglot toolchain -- and I think most of us have one at this point -- then the Spot => OAS => Python process works fine and is easy to set up. You don't even need to start with Spot, of course.
> I like the idea of generic structs and oneofs (which I'm going to implement in some future version). I think if we had an easy way to define generics in cross-language APIs, we'd probably use it a fair amount.
I agree that this is super important. OAS supports it, although it can be hard to read a lot of branches inheritance trees in that particular format.
You can split your definitions into separate files to make it easier (in both Spot and in plain OAS itself).
> I like the idea of having an extensible language, e.g. be able to provide a JSONLogic type. Imagine a field `priceCalculation: JsonLogic<string, number>`. That'd be pretty cool!
This makes sense, but at the end of the day, "JsonLogic<string, number>" is just a text format. With OAS, you can define a regex to validate inputs and outputs, which has been "good enough" in my experience, but definitely falls short of what you want.
What about GraphQL? That seems to have some of the features you're interested in, although the GraphQL paradigm is so different from HTTP (and has some tradeoffs) that I'd understand not even considering it.
Yeah, GraphQL certainly has many of the features that I was looking at here too, and I figure that it's the rough direction in which webdev seems to be going.
I just... like RPCs.
There's also a vague sense of "buttery should work well for multiple services in a way that other methods might struggle to do so." The fact that RPCs are grouped into services means that a load balancer can shift RPCs to different backends based on which buttery service they're talking to. I'm not sure how that actually compares against common solutions, but it IS interesting :)
Thanks for taking the time to think about all these things! It's very helpful for me.
this is one of those problems I've needed to solve for forever, but which i've never explicitly looked up a clean solution for. I can immediately think of 3 instances in the past week where this would have been perfect.
We switched from watchman to entr on the project I'm currently working on because watchman was troublesome to configure and IIRC it completely detaches from the shell as well.
But that's the point of React - providing an abstraction layer over the poor decisions that were made in creating the web.
Apart from Javascript, of course. But that particular "bad decision" is getting modified with every version into something more acceptable ("now with classes!").
I guess the endpoint is that React + Javascript (+ Redux) becomes the defacto language for developing UIs in, and what implements that abstraction layer is immaterial. React-native all the things!
I know I'm a nutter, but I like the type system :)
I like that there's "==" and "===", because that's exactly how I think. It fits my use case of "is this the same value as that?" or "is this really equal to that?" exactly.
I like that types are fluid, flexible and never get in my way.
But there's a religious war here that I think got won by the static type side, so I'm not going there again ;)
