HTTP + OpenAPI compatibility

[maelp]

Is it possible to create OpenAPI documentation easily from the types? A bit like for oRPC (https://orpc.unnoq.com/docs/openapi/openapi-specification)

So I guess it would need to define "routes" for the API, and also possibly zod-style validation for input/output data

[smartboyathome]

In my experience, AsyncAPI is a better fit than OpenAPI for event-driven architectures like this.

[kentonv]

I'm not all that familiar with OpenAPI. But I think the right way to document a Cap'n Web API is to treat it like documenting a TypeScript library. Extract your interfaces into a separate file, put JSDoc comments on them, run some documentation generator on that...? (Though personally as a user I prefer to look directly at the .d.ts rather than some separate web site...)

[maelp]

So I guess it wouldn't be possible for instance to create an interface for other languages (like Python / Go / etc) and it requires Typescript? The good thing about OpenAPI is that it's an interface description, which allows to automatically build a client for the service

[kentonv]

As I understand it -- but again I don't have much experience with it -- OpenAPI is intended to describe REST APIs. That probably makes it a poor fit for describing object-capability RPC APIs.

Cap'n Web is currently designed to play particularly well with TypeScript, so TypeScript is a natural format for describing it. One could even imagine auto-generating APIs in other languages from the TypeScript API. If you stick to fairly normal interfaces and method signatures, TypeScript isn't all that terrible a way to describe a generic cross-language API.

With that said, if you're really looking for a language-neutral schema format for describing a Cap'n-Web-style API, I have another suggestion: Cap'n Proto. :)

Of course, a big selling point of Cap'n Web over Cap'n Proto is that, if you're working in TypeScript already, you don't have to learn some other format for describing interfaces. A lot of people don't like Cap'n Proto specifically because they have to learn such a new format. But if you really prioritize being language-agnostic over ease-of-use in TypeScript specifically, then why not just use Cap'n Proto schemas?

However, at this very moment, you can't use Cap'n Proto schemas with Cap'n Web, because they are actually different wire protocols and there's no way to bridge between them yet. But I think we'll likely be building that. :)

And then if your backend is in Rust or Go, what I'd suggest is writing the backend using Cap'n Proto, putting the capnweb<->capnproto proxy in front of it, and then your browser-side frontend can be Cap'n Web.

(The right answer for Python is a bit less clear. Python is a dynamically-typed language, and it might actually be easier for it to just speak Cap'n Web directly... the type systems are close enough, I think. Needs more research.)

[maelp]

Interesting... my use case would be that on my side, most of my code (backend, frontend, cli, etc) would be typescript, but my own clients might want API-level access with any other language (for some REST-compatible subset of cap'n web)

So basically I would have the "cool features" of cap'n web "for free" when using typescript (like sending objects and methods, etc), and would be able to expose a subset (perhaps with less bells and whistles, "REST-compatible") to other languages for more standard stuff

Right now it "feels" that if I choose to use capnweb for my backend I'd be locked with consumers using Typescript

[kentonv]

Hmm, the thing is, Cap'n Web APIs are generally designed and organized completely differently from REST APIs at a deep level, so it seems hard to design a single API that is somehow automagically offered across both protocols. Instead I think you need to design your Cap'n Web API and your REST API as two independent APIs that happen to expose the same functionality. Perhaps the REST API can be implemented on top of the Cap'n Web one (since Cap'n Web is strictly more expressive), but you're still probably going to need code in there to do that translation since the models are very different.