Even with this valid criticism GraphQL is years ahead of OpenAPI with everything having to do with type safety (I challenge you to write a compex OpenAPI Nest.js project with valid scheme). GraphQL comes with great tooling for consuming types, schema governance and documentation while offering a unique consumer side safety and ergonomics with fragments. Although it’s far from perfect I think it’s the best we got so far and future protocols should start from learning and adopting GraphQLs philosophy
Swagger typedefs are a nightmare, if only for the way that it intermixes details of an object property in with details of the type of that property. It’s way too complicated in some areas, and not descriptive enough in others, the official spec simply leaves out about half of the most important details as “basically like JSON schema” another, even more overcomplicated system.
I haven’t used OpenAPI that much, so I can’t really say that with confidence, but this has been my feeling as well. I agree with you that, type-wise, this is much easier to work with, which I try to convey at the end. I don’t want us to stop at GraphQL though.
Definitely agree with you on OpenAPI. I’ve observed my team and an adjacent team rework their implementations to fit schemas that could be expressed. The result was clunky, confusing, and consistently delayed tasks. One of the key issues was, if I recall, sum types.
I also feel that protobuf ought to get a mention too, especially for GRPC APIs. Protobuf felt more rigid and trustworthy (to review and rely upon over time) as an IDL, while GraphQL was more fun and flexible. GraphQL’s interactive tools (hardly any useful tools exist for GRPC) are so ergonomic that I would not hesitate to recommend it for client to server APIs.
The OpenAPI specification allows using JSON Schema to describe types with quite sophisticated types. It’s really up to the codegen implementation to translate that into something appropriate for the type system of the target language. If anything, it’s probably a bit too powerful for most implementations to cover all the edge cases that can be specified.
In terms of schema governance and documentation it’s not that difficult to upload the schema and its documentation page (kinda trivial with Swagger/Rapidoc/etc.) alongside the API itself.
The distinction between input types and output types is arbitrary and leads to unnecessary duplication
The execution model for queries leaves a lot to be desired. Execution order is only guaranteed at the top level, and it is not possible for one part of a query to depend on another. For us this meant making several API calls when only one should have been needed.
But I absolutely agree with the sibling comment that GraphQL (schema-wise) is better than the popular alternatives, and I hope it evolves to include a more powerful type system.
The distinction between input types and output types is arbitrary and leads to unnecessary duplication
This (along with the fact that interfaces and unions only work with output types) has been a tremendous pain in the ass for us at my workplace where we had a top-down mandate to go “all-in” on graphql in 2018. When we finally got approval to migrate off it earlier this year it was a huge relief.
It’s frustrating because the solution isn’t super obscure or fancy; just the most basic level of doing your homework on type systems would point you in the right direction. But as the post mentions near the end, graphql is designed to be consumed by languages with rudimentary and primitive type systems, and when that’s the overarching design goal, it’s no surprise that the result is a disappointment.
Even with this valid criticism GraphQL is years ahead of OpenAPI with everything having to do with type safety (I challenge you to write a compex OpenAPI Nest.js project with valid scheme). GraphQL comes with great tooling for consuming types, schema governance and documentation while offering a unique consumer side safety and ergonomics with fragments. Although it’s far from perfect I think it’s the best we got so far and future protocols should start from learning and adopting GraphQLs philosophy
Swagger typedefs are a nightmare, if only for the way that it intermixes details of an object property in with details of the type of that property. It’s way too complicated in some areas, and not descriptive enough in others, the official spec simply leaves out about half of the most important details as “basically like JSON schema” another, even more overcomplicated system.
I haven’t used OpenAPI that much, so I can’t really say that with confidence, but this has been my feeling as well. I agree with you that, type-wise, this is much easier to work with, which I try to convey at the end. I don’t want us to stop at GraphQL though.
Definitely agree with you on OpenAPI. I’ve observed my team and an adjacent team rework their implementations to fit schemas that could be expressed. The result was clunky, confusing, and consistently delayed tasks. One of the key issues was, if I recall, sum types.
I also feel that protobuf ought to get a mention too, especially for GRPC APIs. Protobuf felt more rigid and trustworthy (to review and rely upon over time) as an IDL, while GraphQL was more fun and flexible. GraphQL’s interactive tools (hardly any useful tools exist for GRPC) are so ergonomic that I would not hesitate to recommend it for client to server APIs.
The OpenAPI specification allows using JSON Schema to describe types with quite sophisticated types. It’s really up to the codegen implementation to translate that into something appropriate for the type system of the target language. If anything, it’s probably a bit too powerful for most implementations to cover all the edge cases that can be specified.
In terms of schema governance and documentation it’s not that difficult to upload the schema and its documentation page (kinda trivial with Swagger/Rapidoc/etc.) alongside the API itself.
To this, I would add:
But I absolutely agree with the sibling comment that GraphQL (schema-wise) is better than the popular alternatives, and I hope it evolves to include a more powerful type system.
This (along with the fact that interfaces and unions only work with output types) has been a tremendous pain in the ass for us at my workplace where we had a top-down mandate to go “all-in” on graphql in 2018. When we finally got approval to migrate off it earlier this year it was a huge relief.
It’s frustrating because the solution isn’t super obscure or fancy; just the most basic level of doing your homework on type systems would point you in the right direction. But as the post mentions near the end, graphql is designed to be consumed by languages with rudimentary and primitive type systems, and when that’s the overarching design goal, it’s no surprise that the result is a disappointment.