bitspittle
commented
1 year ago Thank you for the comment, I appreciate the detail.
I do love the idea of creating an interface in common code that can be used to define an endpoint. If done right, it would be a nice option to define type-safe APIs.
I'd have to think it through to make sure it would actually come together, my guess is there are more technical issues / complexity to get this working than I think.
That said, I'll be up front with you: I won't be able to prioritize this for quite a while. There is still so much to do on the rest of Kobweb, and until recently, no one was even really using server APIs at all (even though they're one of the earliest featured I designed!). Most people (including myself actually) use static layout exports.
I'll keep this issue open for now, and if you're interested, we can even discuss external contributions.
At the same time, if you're using "post" (or some http method that takes a body), check out the examples/todo example, where I show how to use serialization on both client and server to have some type-safe communication between them.
If I understand it correctly, server side API endpoints in kobweb essentially consist of:
on the server, and
on the client.
This means that you have to manually keep track of all the parameter and return types as well as URL-s for endpoints when making requests on the client. Whenever you change something on the server you have to manually update the corresponding API calls on the client to match. Especially for larger projects this is a signifficant source of development overhead that I feel could be elliminated in kobweb.
My feature request is that kobweb provide a statically typed way to define request parameters on the server (the design I had in mind is something in the style of FastAPI in Python, but I do not have a concrete proposal here), as well some way to statically and automatically typecheck requests on the client (for example by automatically generating an API client, or possibly by allowing the developer to define an interface that is implemented with endpoint handlers on the server and with autogenerated api calls on the client).
For prior art, KVision uses service interfaces, which are implemented by the developer on the server and turned into API endpoints. The same interface is then automatically implemented on the client using autogenerated requests to those endpoints. (See https://kvision.gitbook.io/kvision-guide/6.-full-stack-development-guide/client-side for more details) I think this basic concept works well enough, but personally I dislike how non-idiomatic the generated API endpoints are (in terms of web API-s) and how inconvenient it is to debug and inspect them using built-in browser tooling.