[HN Gopher] Beyond OpenAPI
___________________________________________________________________
Beyond OpenAPI
Author : nalgeon
Score : 137 points
Date : 2023-09-11 12:26 UTC (9 hours ago)
(HTM) web link (antonz.org)
(TXT) w3m dump (antonz.org)
| simonw wrote:
| What kind of sandbox are you using here for running Python/etc
| code on your server?
| mdaniel wrote:
| 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>
|
| I've always heard "containerization is not a security boundary"
| but I am not red-team enough to provide specific counter-
| examples
| rkeene2 wrote:
| 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
|
| [1] https://browser.appfs.net/
| [deleted]
| lux wrote:
| 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 wrote:
| 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...
| sigwinch28 wrote:
| > According to the popular classification, there are four
| document types: tutorials, how-to guides, technical references,
| and explanations.
|
| This is Diataxis: https://diataxis.fr/
| pphysch wrote:
| 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?
| pattycakes wrote:
| 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.
| tevon wrote:
| 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 wrote:
| I built this because I had the same idea:
| 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.
| marcopicentini wrote:
| Would be very interesting to see the same documentation
| principles applied to other thing (not API or developer docs).
| ebiester wrote:
| I mean, there is nothing stopping people from using the
| [Diataxis Framework](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 wrote:
| 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...
| stared wrote:
| 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, it is not
| available for accounts that have access to its 8k-token variant,
| gpt-4-32k.
| simonw wrote:
| This is about OpenAPI, not OpenAI.
| stared wrote:
| My bad!
| freeqaz wrote:
| 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 wrote:
| 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]
| eyelidlessness wrote:
| 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.
| jicea wrote:
| 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
|
| - HTTP Client https://www.jetbrains.com/help/idea/http-client-in-
| product-c...
|
| - httpYac https://httpyac.github.io
|
| - restclient.el https://github.com/pashky/restclient.el
|
| - REST Client https://github.com/Huachao/vscode-restclient
|
| - verb https://github.com/federicotdn/verb
|
| And many more...
|
| Worth noting, other tools have taken the YAML route (like Step CI
| https://stepci.com), JavaScript (k6
| 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
| [deleted]
| yellow_lead wrote:
| 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 wrote:
| 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 wrote:
| Yeah that looks great for a blog post .. . Good luck writing
| and maintaining that for a real project in the real world
| [deleted]
| boxed wrote:
| 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
|
| corresponding documentation/tests: https://github.com/iommi
| rocks/iommi/blob/master/docs/test_do...
|
| my evil hack to get this working: https://github.com/iommir
| ocks/iommi/blob/master/make_doc_rst... and https://github.c
| om/iommirocks/iommi/blob/master/iommi/docs.p...
| btown wrote:
| That's brilliant! 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!
| williamdclt wrote:
| Many projects maintain different document types in their
| docs. Of the top of my head: NestJS.
| mirekrusin wrote:
| Or use jsonrpc and your documentation is ie typescript definition
| file, a list of function signatures.
| simonw wrote:
| 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/ - 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/ 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 wrote:
| 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]
| sharemywin wrote:
| [flagged]
| troupo wrote:
| What this misses is the curl response format.
|
| Long time ago at Klarna we used this tool:
| https://github.com/for-GET/katt Here's an example:
| https://github.com/for-GET/katt/blob/master/doc/example-http...
___________________________________________________________________
(page generated 2023-09-11 22:00 UTC)