6 ms·

Beyond OpenAPI

168 points by nalgeon 3y ago

sharemywin 3y ago
[flagged]
marcopicentini 3y ago
Would be very interesting to see the same documentation principles applied to other thing (not API or developer docs).
- ebiester 3y ago
  I mean, there is nothing stopping people from using the [Diataxis Framework](https://diataxis.fr/ https://diataxis.fr/) for any sort of documentation - it just doesn't have as great a foothold outside our sphere. I was a bit surprised it or Divio (where it was created) announced when they talked about the four types of documentation. I would love to see it make its way into information systems curriculum, as it's a quite useful mental model.
  - spondylosaurus 3y ago
    I go back and forth on the usefulness of Diataxis and related information frameworks—Mark Baker (of EPPO fame) has an interesting series[1] about the DITA equivalent of task, concept, and reference: > If there is a problem with DITA, then, it is not that it lacks a theory of information design. The problem is that many people actually believe that it does have a theory of information design, and that that theory can be summed up in three words: concept, task, and reference. But a theory for breaking content up into pieces is not a theory of information design unless it also includes a theory of how the pieces should go back together. > There is, of course, nothing preventing DITA users from having or developing a sound theory about how the pieces should go back together. The problem is not that DITA does not provide one. The problem is that writers often do not see that they need one. They believe, or act as if they believed, that the devolution into concept, task, and reference is a complete information design. The result, generally, is Frankenbooks. Which I think is a salient point, and less an indictment on the "three/four types" model than a reminder that you shouldn't just throw together a bunch of type-delineated docs for their on sake; the individual pieces have to make a functional whole. So I'm certainly in favor of supplementing traditional OpenAPI-esque reference docs with more conceptual or task-based docs... provided that they're actually designed to complement each other. [1] https://everypageispageone.com/2012/07/28/the-tyranny-of-the-terrible-troika-rethinking-concept-task-and-reference/ https://everypageispageone.com/2012/07/28/the-tyranny-of-the...
yellow_lead 3y ago
I would prefer reading the OpenAPI spec for an API - which is in a standardized format and has easily searchable/skip-able sections, like schemas, endpoints, etc. An interactive tutorial that you mostly read from beginning to end is not convenient for devs - we want to find things within a few seconds of hitting the docs page.
- williamdclt 3y ago
  The point of the article is not to _replace_ the spec. The point of the "four-document types" model is that different document types fit different use-cases.
  - gdsdfe 3y ago
    Yeah that looks great for a blog post .. . Good luck writing and maintaining that for a real project in the real world
    - boxed 3y ago
      It's all about the tooling. I wrote my own for iommi where the html output of some code gets saved in a defined place, and then the finished documentation page embeds that html in an iframe. It's not only WAY WAY easier to maintain than a bunch of screenshots, but I found a ton of issues with the documentation after I made it so it runs all the examples and I can look at the output. example: https://docs.iommi.rocks/en/latest/cookbook_forms.html https://docs.iommi.rocks/en/latest/cookbook_forms.html corresponding documentation/tests: https://github.com/iommirocks/iommi/blob/master/docs/test_doc_cookbook_forms.py https://github.com/iommirocks/iommi/blob/master/docs/test_do... my evil hack to get this working: https://github.com/iommirocks/iommi/blob/master/make_doc_rsts.py https://github.com/iommirocks/iommi/blob/master/make_doc_rst... and https://github.com/iommirocks/iommi/blob/master/iommi/docs.py https://github.com/iommirocks/iommi/blob/master/iommi/docs.p...
      - btown 3y ago
        That's brilliant! https://github.com/scientific-python/pytest-doctestplus https://github.com/scientific-python/pytest-doctestplus seems to be similar working in the opposite direction, using the documentation source as the single location for test code. I like your approach better and wish there was more support for that pattern more generally!
troupo 3y ago
What this misses is the curl response format. Long time ago at Klarna we used this tool: https://github.com/for-GET/katt https://github.com/for-GET/katt Here's an example: https://github.com/for-GET/katt/blob/master/doc/example-httpbin.apib https://github.com/for-GET/katt/blob/master/doc/example-http...
simonw 3y ago
What kind of sandbox are you using here for running Python/etc code on your server?
- deleted 3y ago
  [deleted]
- mdaniel 3y ago
  I'm not associated with the site, but using their bash one as an example it appears to just be docker <https://codapi.org/bash/#cat%20%2Fproc%2F1%2Fmounts https://codapi.org/bash/#cat%20%2Fproc%2F1%2Fmounts> I've always heard "containerization is not a security boundary" but I am not red-team enough to provide specific counter-examples
  - rkeene2 3y ago
    If you do want a stronger security boundary, you can do that without using cgroups and other kinds of namespaces (aside from chroot) pretty easily using something like `firejail` -- that's what I do for this demo [0] (all the software is in /opt/appfs, if you want to try stuff out -- you can browse it here [1]) [0] https://rkeene.dev/js-repl/?arg=bash https://rkeene.dev/js-repl/?arg=bash [1] https://browser.appfs.net/ https://browser.appfs.net/
tevon 3y ago
I was hopeful starting this article. Because I do think we need something better than OpenAPI for self-documenting APIs... The idea of an interactive tutorial is great, but as others have mentioned, likely very difficult to maintain over time.
- hitchstory 3y ago
  I built this because I had the same idea: https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory If your specification is self rewriting, can be tested and can be used to generate docs then maintenance costs plummet.
freeqaz 3y ago
I hate that my brain has now reprogrammed this to mean "ChatGPT" (OpenAI) to me. I legit opened the link and expected to read about "Beyond LLMs" or somebody leaving work at OpenAI. But HTTP APIs with types are pretty cool too. Carry on, please!
- willio58 3y ago
  At my job we recently implemented OpenAPI and it's been painful hearing people call it OpenAI on zoom calls but it makes sense, they're so darn close.
- deleted 3y ago
  [deleted]
simonw 3y ago
I think people may be missing the core point of this article. As often happens on Hacker News (and the internet in general), people are responding more to the post title than the actual content. Anton has built a new thing, https://codapi.org/ https://codapi.org/ - which provides a web component that makes it easy to embed interactive code snippets for HTTP APIs, Python code and more directly in pages of documentation. This article demonstrates this new technology in the context of the https://diataxis.fr/ https://diataxis.fr/ documentation framework, which recommends going beyond just straight API reference documentation and ensuring you cover tutorials, how-to guides and explanations as well. I think this is really cool.
- kaycebasques 3y ago
  I read the full post. It meanders quite a bit. Would have been more effective to just announce the new tool without the provocative title or the detour into HTTP basics. Sending this comment in the spirit of friendly, respectful, constructive criticism.
- deleted 3y ago
  [deleted]
lux 3y ago
One thing that trips me up when I see this 4 quadrant structure for documentation is when to go with a tutorial and when to go with a how-to. Curious how others delineate between those.
- kaycebasques 3y ago
  Tutorial takes you from an exact point A to an exact point B. Guide is much "looser" and just describes the general steps to get something done, without making any type of guarantee of being able to take you exactly from A to B. Mostly out of acknowledgment that the real-world is messy and everyone is going to have a slightly different system. Tutorial is for people starting from scratch or who want a gentle hands-on intro to your thing, guide is for people who are doing messy integration work with existing systems. It's not a perfect delineator but it'll get you most of the way there...
  - juancampa 3y ago
    The way I think about it is: - Tutorial: learn how the system works - How-to: recipes for common use-cases
- layer8 3y ago
  Tutorial is a Getting Started, with no specific goal other than to serve as a general hands-on introduction. It does not assume any prior experience with the tool/product. How-to(s) is a cookbook, targeting specific use cases, and may not particularly cater to novices.
- ketozhang 3y ago
  In diataxis, a tutorial serves your education and a how-to guide serves your work. Following this standard, a tutorial may contain a simpler or more contrived example; it may contain things you'd never do in production.
stared 3y ago
While I like it, it also has shortcomings. For example, while gpt-4-32k is listed in https://platform.openai.com/docs/models/gpt-4 https://platform.openai.com/docs/models/gpt-4, it is not available for accounts that have access to its 8k-token variant, gpt-4-32k.
- simonw 3y ago
  This is about OpenAPI, not OpenAI.
  - stared 3y ago
    My bad!
  - joshxyz 3y ago
    this made my day
eyelidlessness 3y ago
OpenAPI has great affordances for providing examples along with pertinent documentation sections. Many OpenAPI UIs provide ways to execute those examples or other interactive ways to populate and try requests. These could surely be better honed for the how-to guide style of documentation! But I think that’s probably a better place to start for people who are starting at, and looking to go beyond, what OpenAPI currently provides.
deleted 3y ago
[deleted]
sigwinch28 3y ago
> According to the popular classification, there are four document types: tutorials, how-to guides, technical references, and explanations. This is Diátaxis: https://diataxis.fr/ https://diataxis.fr/
jicea 3y ago
The "HTTP" format proposed in the article is the same we use with Hurl [1], an Open Source HTTP CLI based on plain text. POST http://httpbingo.org/anything/chat content-type: application/json { "message": "Hello!" } We extend it a bit to add checks on response, and add request chaining, but it's basically HTTP 1.x as this article shows it. A lot of others tools have the same idea, with minor differences: - Hurl (I'm one of the maintainer) https://hurl.dev https://hurl.dev - HTTP Client https://www.jetbrains.com/help/idea/http-client-in-product-code-editor.html https://www.jetbrains.com/help/idea/http-client-in-product-c... - httpYac https://httpyac.github.io https://httpyac.github.io - restclient.el https://github.com/pashky/restclient.el https://github.com/pashky/restclient.el - REST Client https://github.com/Huachao/vscode-restclient https://github.com/Huachao/vscode-restclient - verb https://github.com/federicotdn/verb https://github.com/federicotdn/verb And many more... Worth noting, other tools have taken the YAML route (like Step CI https://stepci.com https://stepci.com), JavaScript (k6 https://k6.io/docs/using-k6/http-requests/ https://k6.io/docs/using-k6/http-requests/)... I'm biased of course, I've a tiny preference for the simple plain text format. And of course, there are also GUI application (Postman, Insomnia, RecipeUI amon others) [1]: https://hurl.dev https://hurl.dev
mirekrusin 3y ago
Or use jsonrpc and your documentation is ie typescript definition file, a list of function signatures.
- verdverm 3y ago
  most things are not written in typescript OpenAPI, being JSON or Yaml, is portable
  - mirekrusin 3y ago
    JsonRPC is also portable. Whole spec fits single page.
    - verdverm 3y ago
      the JsonRPC comes from the typescript in GP, so the process of schema generation from types is not portable to other languages...
      - mirekrusin 3y ago
        Typescript is mentioned as an example of function signature format. As it needs to describe only valid json values, the whole language needs to operate on 6 underlying data types only - it's really not that complicated to come up with minimal readable format that's easy to parse. It doesn't matter much if it reassembles ts, flow, ocaml or haskell - the point is it can fit into single screen, serve as documentation and be parseable for verification/codegen etc.
        verdverm 3y ago
        Let's step back, and remember you posed JsonRPC as an alternative to OpenAPI or something like that? There is a whole lot more to express than... > 6 underlying data types only ... when automating REST documentation from some underlying source of truth It seems this one-page spec is woefully insufficient to express the concepts that OpenAPI can. Hence why no one here thinks this is a viable alternative
pattycakes 3y ago
OpenAPI is more than just documentation generation, it’s also used for runtime time validation and codegen for both client and server stubs. I’d argue that what’s discussed in this article can complement OpenAPI but doesn’t replace it.
pphysch 3y ago
codapi is slick and this tutorial provides good insight into how HTTP APIs work. OpenAPI is wack though. It doesn't provide any guarantees that the API does what it is supposed to do. I think in most cases it is a distraction and developer time would be better spent understanding HTTP and implementing and testing the endpoints. I'm curious if others have had good experiences consuming OpenAPI as intended, i.e. you get handed a new API and you generate the code interfaces and plug them directly into your business logic without writing any extra wrappers. Or do you end up writing lots of wrapping code anyways?
echan00 3y ago
[flagged]
azophy_2 3y ago
this thread reminds me of another thread [1] several days ago about web component using WASI runtime (runno.dev), which may have overlapping usecases with this project. worth looking [1] https://news.ycombinator.com/item?id=37287339 https://news.ycombinator.com/item?id=37287339

Beyond OpenAPI

168 points by nalgeon 3y ago

sharemywin 3y ago

[flagged]

marcopicentini 3y ago

Would be very interesting to see the same documentation principles applied to other thing (not API or developer docs).

ebiester 3y ago
I mean, there is nothing stopping people from using the [Diataxis Framework](https://diataxis.fr/ https://diataxis.fr/) for any sort of documentation - it just doesn't have as great a foothold outside our sphere. I was a bit surprised it or Divio (where it was created) announced when they talked about the four types of documentation. I would love to see it make its way into information systems curriculum, as it's a quite useful mental model.
- spondylosaurus 3y ago
  I go back and forth on the usefulness of Diataxis and related information frameworks—Mark Baker (of EPPO fame) has an interesting series[1] about the DITA equivalent of task, concept, and reference: > If there is a problem with DITA, then, it is not that it lacks a theory of information design. The problem is that many people actually believe that it does have a theory of information design, and that that theory can be summed up in three words: concept, task, and reference. But a theory for breaking content up into pieces is not a theory of information design unless it also includes a theory of how the pieces should go back together. > There is, of course, nothing preventing DITA users from having or developing a sound theory about how the pieces should go back together. The problem is not that DITA does not provide one. The problem is that writers often do not see that they need one. They believe, or act as if they believed, that the devolution into concept, task, and reference is a complete information design. The result, generally, is Frankenbooks. Which I think is a salient point, and less an indictment on the "three/four types" model than a reminder that you shouldn't just throw together a bunch of type-delineated docs for their on sake; the individual pieces have to make a functional whole. So I'm certainly in favor of supplementing traditional OpenAPI-esque reference docs with more conceptual or task-based docs... provided that they're actually designed to complement each other. [1] https://everypageispageone.com/2012/07/28/the-tyranny-of-the-terrible-troika-rethinking-concept-task-and-reference/ https://everypageispageone.com/2012/07/28/the-tyranny-of-the...

yellow_lead 3y ago

I would prefer reading the OpenAPI spec for an API - which is in a standardized format and has easily searchable/skip-able sections, like schemas, endpoints, etc. An interactive tutorial that you mostly read from beginning to end is not convenient for devs - we want to find things within a few seconds of hitting the docs page.

williamdclt 3y ago
The point of the article is not to _replace_ the spec. The point of the "four-document types" model is that different document types fit different use-cases.
- gdsdfe 3y ago
  Yeah that looks great for a blog post .. . Good luck writing and maintaining that for a real project in the real world
  - boxed 3y ago
    It's all about the tooling. I wrote my own for iommi where the html output of some code gets saved in a defined place, and then the finished documentation page embeds that html in an iframe. It's not only WAY WAY easier to maintain than a bunch of screenshots, but I found a ton of issues with the documentation after I made it so it runs all the examples and I can look at the output. example: https://docs.iommi.rocks/en/latest/cookbook_forms.html https://docs.iommi.rocks/en/latest/cookbook_forms.html corresponding documentation/tests: https://github.com/iommirocks/iommi/blob/master/docs/test_doc_cookbook_forms.py https://github.com/iommirocks/iommi/blob/master/docs/test_do... my evil hack to get this working: https://github.com/iommirocks/iommi/blob/master/make_doc_rsts.py https://github.com/iommirocks/iommi/blob/master/make_doc_rst... and https://github.com/iommirocks/iommi/blob/master/iommi/docs.py https://github.com/iommirocks/iommi/blob/master/iommi/docs.p...
    - btown 3y ago
      That's brilliant! https://github.com/scientific-python/pytest-doctestplus https://github.com/scientific-python/pytest-doctestplus seems to be similar working in the opposite direction, using the documentation source as the single location for test code. I like your approach better and wish there was more support for that pattern more generally!

troupo 3y ago

What this misses is the curl response format. Long time ago at Klarna we used this tool: https://github.com/for-GET/katt https://github.com/for-GET/katt Here's an example: https://github.com/for-GET/katt/blob/master/doc/example-httpbin.apib https://github.com/for-GET/katt/blob/master/doc/example-http...

simonw 3y ago

What kind of sandbox are you using here for running Python/etc code on your server?

deleted 3y ago
[deleted]
mdaniel 3y ago
I'm not associated with the site, but using their bash one as an example it appears to just be docker <https://codapi.org/bash/#cat%20%2Fproc%2F1%2Fmounts https://codapi.org/bash/#cat%20%2Fproc%2F1%2Fmounts> I've always heard "containerization is not a security boundary" but I am not red-team enough to provide specific counter-examples
- rkeene2 3y ago
  If you do want a stronger security boundary, you can do that without using cgroups and other kinds of namespaces (aside from chroot) pretty easily using something like `firejail` -- that's what I do for this demo [0] (all the software is in /opt/appfs, if you want to try stuff out -- you can browse it here [1]) [0] https://rkeene.dev/js-repl/?arg=bash https://rkeene.dev/js-repl/?arg=bash [1] https://browser.appfs.net/ https://browser.appfs.net/

tevon 3y ago

I was hopeful starting this article. Because I do think we need something better than OpenAPI for self-documenting APIs... The idea of an interactive tutorial is great, but as others have mentioned, likely very difficult to maintain over time.

hitchstory 3y ago
I built this because I had the same idea: https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory If your specification is self rewriting, can be tested and can be used to generate docs then maintenance costs plummet.

freeqaz 3y ago

I hate that my brain has now reprogrammed this to mean "ChatGPT" (OpenAI) to me. I legit opened the link and expected to read about "Beyond LLMs" or somebody leaving work at OpenAI. But HTTP APIs with types are pretty cool too. Carry on, please!

willio58 3y ago
At my job we recently implemented OpenAPI and it's been painful hearing people call it OpenAI on zoom calls but it makes sense, they're so darn close.
deleted 3y ago
[deleted]

simonw 3y ago

I think people may be missing the core point of this article. As often happens on Hacker News (and the internet in general), people are responding more to the post title than the actual content. Anton has built a new thing, https://codapi.org/ https://codapi.org/ - which provides a web component that makes it easy to embed interactive code snippets for HTTP APIs, Python code and more directly in pages of documentation. This article demonstrates this new technology in the context of the https://diataxis.fr/ https://diataxis.fr/ documentation framework, which recommends going beyond just straight API reference documentation and ensuring you cover tutorials, how-to guides and explanations as well. I think this is really cool.

kaycebasques 3y ago
I read the full post. It meanders quite a bit. Would have been more effective to just announce the new tool without the provocative title or the detour into HTTP basics. Sending this comment in the spirit of friendly, respectful, constructive criticism.
deleted 3y ago
[deleted]

lux 3y ago

One thing that trips me up when I see this 4 quadrant structure for documentation is when to go with a tutorial and when to go with a how-to. Curious how others delineate between those.

kaycebasques 3y ago
Tutorial takes you from an exact point A to an exact point B. Guide is much "looser" and just describes the general steps to get something done, without making any type of guarantee of being able to take you exactly from A to B. Mostly out of acknowledgment that the real-world is messy and everyone is going to have a slightly different system. Tutorial is for people starting from scratch or who want a gentle hands-on intro to your thing, guide is for people who are doing messy integration work with existing systems. It's not a perfect delineator but it'll get you most of the way there...
- juancampa 3y ago
  The way I think about it is: - Tutorial: learn how the system works - How-to: recipes for common use-cases
layer8 3y ago
Tutorial is a Getting Started, with no specific goal other than to serve as a general hands-on introduction. It does not assume any prior experience with the tool/product. How-to(s) is a cookbook, targeting specific use cases, and may not particularly cater to novices.
ketozhang 3y ago
In diataxis, a tutorial serves your education and a how-to guide serves your work. Following this standard, a tutorial may contain a simpler or more contrived example; it may contain things you'd never do in production.

stared 3y ago

While I like it, it also has shortcomings. For example, while gpt-4-32k is listed in https://platform.openai.com/docs/models/gpt-4 https://platform.openai.com/docs/models/gpt-4, it is not available for accounts that have access to its 8k-token variant, gpt-4-32k.

simonw 3y ago
This is about OpenAPI, not OpenAI.
- stared 3y ago
  My bad!
- joshxyz 3y ago
  this made my day

eyelidlessness 3y ago

OpenAPI has great affordances for providing examples along with pertinent documentation sections. Many OpenAPI UIs provide ways to execute those examples or other interactive ways to populate and try requests. These could surely be better honed for the how-to guide style of documentation! But I think that’s probably a better place to start for people who are starting at, and looking to go beyond, what OpenAPI currently provides.

deleted 3y ago

[deleted]

sigwinch28 3y ago

> According to the popular classification, there are four document types: tutorials, how-to guides, technical references, and explanations. This is Diátaxis: https://diataxis.fr/ https://diataxis.fr/

jicea 3y ago

The "HTTP" format proposed in the article is the same we use with Hurl [1], an Open Source HTTP CLI based on plain text. POST http://httpbingo.org/anything/chat content-type: application/json { "message": "Hello!" } We extend it a bit to add checks on response, and add request chaining, but it's basically HTTP 1.x as this article shows it. A lot of others tools have the same idea, with minor differences: - Hurl (I'm one of the maintainer) https://hurl.dev https://hurl.dev - HTTP Client https://www.jetbrains.com/help/idea/http-client-in-product-code-editor.html https://www.jetbrains.com/help/idea/http-client-in-product-c... - httpYac https://httpyac.github.io https://httpyac.github.io - restclient.el https://github.com/pashky/restclient.el https://github.com/pashky/restclient.el - REST Client https://github.com/Huachao/vscode-restclient https://github.com/Huachao/vscode-restclient - verb https://github.com/federicotdn/verb https://github.com/federicotdn/verb And many more... Worth noting, other tools have taken the YAML route (like Step CI https://stepci.com https://stepci.com), JavaScript (k6 https://k6.io/docs/using-k6/http-requests/ https://k6.io/docs/using-k6/http-requests/)... I'm biased of course, I've a tiny preference for the simple plain text format. And of course, there are also GUI application (Postman, Insomnia, RecipeUI amon others) [1]: https://hurl.dev https://hurl.dev

mirekrusin 3y ago

Or use jsonrpc and your documentation is ie typescript definition file, a list of function signatures.

verdverm 3y ago
most things are not written in typescript OpenAPI, being JSON or Yaml, is portable
- mirekrusin 3y ago
  JsonRPC is also portable. Whole spec fits single page.
  - verdverm 3y ago
    the JsonRPC comes from the typescript in GP, so the process of schema generation from types is not portable to other languages...
    - mirekrusin 3y ago
      Typescript is mentioned as an example of function signature format. As it needs to describe only valid json values, the whole language needs to operate on 6 underlying data types only - it's really not that complicated to come up with minimal readable format that's easy to parse. It doesn't matter much if it reassembles ts, flow, ocaml or haskell - the point is it can fit into single screen, serve as documentation and be parseable for verification/codegen etc.
      - verdverm 3y ago
        Let's step back, and remember you posed JsonRPC as an alternative to OpenAPI or something like that? There is a whole lot more to express than... > 6 underlying data types only ... when automating REST documentation from some underlying source of truth It seems this one-page spec is woefully insufficient to express the concepts that OpenAPI can. Hence why no one here thinks this is a viable alternative

pattycakes 3y ago

OpenAPI is more than just documentation generation, it’s also used for runtime time validation and codegen for both client and server stubs. I’d argue that what’s discussed in this article can complement OpenAPI but doesn’t replace it.

pphysch 3y ago

codapi is slick and this tutorial provides good insight into how HTTP APIs work. OpenAPI is wack though. It doesn't provide any guarantees that the API does what it is supposed to do. I think in most cases it is a distraction and developer time would be better spent understanding HTTP and implementing and testing the endpoints. I'm curious if others have had good experiences consuming OpenAPI as intended, i.e. you get handed a new API and you generate the code interfaces and plug them directly into your business logic without writing any extra wrappers. Or do you end up writing lots of wrapping code anyways?

echan00 3y ago

[flagged]

azophy_2 3y ago

this thread reminds me of another thread [1] several days ago about web component using WASI runtime (runno.dev), which may have overlapping usecases with this project. worth looking [1] https://news.ycombinator.com/item?id=37287339 https://news.ycombinator.com/item?id=37287339