3 ms·

For client-server APIs, I'd say it's using OpenAPI as specification, as opposed to just for documentation and testing. It feels like it shouldn't be "cutting e

For client-server APIs, I'd say it's using OpenAPI as specification, as opposed to just for documentation and testing. It feels like it shouldn't be "cutting edge", but it's still not used as much as it should be.

sam_lowry_ 5y ago
OpenAPI must die. It allows to describe REST in a quite limiting manner. There's only one way to implement callbacks. There is no Websocket support nor any hint at async communication protocols. OpenAPI is OK for prototyping, but production-grade performance-tuned software will likely break out of what OpenAPI allows to spec.
- BerislavLopac 5y ago
  > There is no Websocket support nor any hint at async communication protocols. Both of these things are out of scope for OpenAPI. It's a separate discussion whether they should be or not, but they are currently not. For async protocols, there is AsyncAPI [0], FWIW. Do you know of an alternative spec format that would cover what you're missing with OpenAPI?
  - sam_lowry_ 5y ago
    Anything that stands between the programmer and the code is doomed to be abused by those who can't. The whole concept of specifying an API in a DSL should be limited to the domain and not be standardised. OTOH, I am all for literate programming that combines the art of writing prose and code like in Jupiter Notebook. Among competitors to OpenAPI I keep an eye on API Blueprint. While it leans more towards prose than code, it is a valuable tool to document APIs.
    - BerislavLopac 5y ago
      > Anything that stands between the programmer and the code is doomed to be abused by those who can't. Those who can't what? If you mean the ability to code, I don't understand how is that related to API specifications. > The whole concept of specifying an API in a DSL should be limited to the domain and not be standardised. Why exactly?
JoBrad 5y ago
I really like the idea of OpenAPI: use your input and output data models to document your API, and maybe even stub out the framework for your actual code or a language-specific SDK. But the reality is that deviations in auth, data types, etc., end up complicating your OpenAPI specs way more than expected. And the tooling that is supposed to stub out doc sites using your OpenAPI specs is all over the place in terms of what is and isn’t supported, and even how the same supported features are implemented. My team ended up making a custom redoc implementation for our docs site (to include better narrative), but the specs are just for documentation, and don’t inform the application or SDKs at all. Reality is so close to the dream, but in my experience, still so far away.

sam_lowry_ 5y ago

OpenAPI must die. It allows to describe REST in a quite limiting manner. There's only one way to implement callbacks. There is no Websocket support nor any hint at async communication protocols. OpenAPI is OK for prototyping, but production-grade performance-tuned software will likely break out of what OpenAPI allows to spec.

BerislavLopac 5y ago
> There is no Websocket support nor any hint at async communication protocols. Both of these things are out of scope for OpenAPI. It's a separate discussion whether they should be or not, but they are currently not. For async protocols, there is AsyncAPI [0], FWIW. Do you know of an alternative spec format that would cover what you're missing with OpenAPI?
- sam_lowry_ 5y ago
  Anything that stands between the programmer and the code is doomed to be abused by those who can't. The whole concept of specifying an API in a DSL should be limited to the domain and not be standardised. OTOH, I am all for literate programming that combines the art of writing prose and code like in Jupiter Notebook. Among competitors to OpenAPI I keep an eye on API Blueprint. While it leans more towards prose than code, it is a valuable tool to document APIs.
  - BerislavLopac 5y ago
    > Anything that stands between the programmer and the code is doomed to be abused by those who can't. Those who can't what? If you mean the ability to code, I don't understand how is that related to API specifications. > The whole concept of specifying an API in a DSL should be limited to the domain and not be standardised. Why exactly?

JoBrad 5y ago

I really like the idea of OpenAPI: use your input and output data models to document your API, and maybe even stub out the framework for your actual code or a language-specific SDK. But the reality is that deviations in auth, data types, etc., end up complicating your OpenAPI specs way more than expected. And the tooling that is supposed to stub out doc sites using your OpenAPI specs is all over the place in terms of what is and isn’t supported, and even how the same supported features are implemented. My team ended up making a custom redoc implementation for our docs site (to include better narrative), but the specs are just for documentation, and don’t inform the application or SDKs at all. Reality is so close to the dream, but in my experience, still so far away.