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.
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.
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.
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!
I started with that approach actually. It turned untenable after a while. It's just much nicer to have the documentation just a part of your normal test suite without any preprocessing. That also means you get coverage in the normal way too.
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:
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.
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...
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.
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.
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.
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])
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?
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.
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.
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
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 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.
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!
If flow adoption in js bothers you, just replace it with "subset of ts" - it'd look almost the same (it's better when it comes to things like declaring exact vs inexact object types or having cosmetic shorthand for optional type).
The bottom line is that description is terse and natural. Ie. it can be generated directly from your code and code can be generated out of it.
Instead of describing protocol (headers, status codes, http verbs, redirects, urls, params, cookies, content types etc) - you describe function signatures - the very thing that already has first class support in your programming language. An api feels like a library.
Because it uses json as serialization the data types you need to cover are very small - there are no interfaces, classes, inheritance, functions (you can't provide or return objects that define functions) - everything is pretty much composed out of type aliases and unions on 6 basic json types.
Instead of programming in yaml to describe http protocol you work with functions having json on input and output - something that is natural to your host programming language already.
Think graphql but without its nonsense restrictions on query (unions on input are fine!) or cherry picking output (calling convention that is foreign to programming languages and requires embedding dsl/dedicated query engines).
Think more like header file for remote service constraint to list of functions and notifications using json as data type.
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.
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
OpenAPI is cluttered with protocol specifics that are irrelevant to something that is native to your host language (function signatures). Think of it as header file for api that is highly constrained (functions, notifications and json data types only - no classes, instances, polymorphism, no way to encode callbacks or returning functions etc. just basic algebra on json types - type aliases and unions).
Imagine api like this:
// @endpoint wss://localhost:3000/api/v1
notification heartbeat = {
timestamp: number
}
type User = {
id: string,
email: Email
type: "normal" | "admin"
}
type AuthError = {
message: string,
code: -123
}
type NotLoggedInError = {
message: string,
code: -124
}
// Logs you in.
//
// @throws AuthError
login(username: string, password): User
// Adds two numbers.
// @throws NotLoggedInError
add(x: number, y: number): number
// Logs you out.
// @throws NotLoggedInError
logout(): null
It's terse, straight forward and maps to your host programming language naturally.
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.
