API support

[akhayyat]

Thank you for putting Pagoda together and for sharing it!

I could not find any examples for implementing API endpoints. What's the best way to do that in Pagoda? And can that be added to the docs?

Also, would it be possible to use the same controller or function to implement a json response and an HTML (template) response, and respond with either based on the request (content-type request header, for example)?

[mikestefanello]

You're very welcome. I'm glad to hear it's been useful for you.

That's a good question. When I put this together, I wasn't thinking about it as a solution for an API but there's no reason you can't use it for that. I was considering doing a separate project made specifically for that.

For a JSON response, in your controller, rather than using the Page and returning RenderPage(), you can just use the JSON() method provided by the echo.Context that is passed in. See here: https://echo.labstack.com/docs/response#send-json

To determine the content-type, this should work: ctx.Request().Header.Get("Content-Type")

Perhaps the Page can be extended so that RenderPage() automatically checks the content type, and if JSON is request, it renders what is in Page.Data as JSON. I'm not sure how useful that would be though.

Let me know if that works and if you have any ideas or feedback for anything that may make sense to include in this project.

Thanks

[gedw99]

@mikestefanello are you opposed to code gen for the API ? OpenAPI for example.

Its leads to the question of how HTML and HTMX access uses the API. As far as I can see there is no HTMX push style operations ( in this code base ) where you update parts of a html page on the client based on events on the backend ? The reason I bring this up is because I have also been code generating using Async API, which models async style patterns.

https://www.asyncapi.com is the web site

https://www.asyncapi.com/tools for tools

https://github.com/swaggest/go-asyncapi is a simple one. Not a code gen

https://github.com/lerenn/asyncapi-codegen is one I use. It's a code gen, and coupled to NATS.

NATS then allows a lot more things for Pagoda to do. Notifications, etc. HTMX can use SSE and Web sockets to allow changes to the backend to update the GUI too.

[mikestefanello]

@gedw99 As I mentioned, the primary purpose of this project isn't for developing an API but rather a SSR web app. Nothing stops you from using this for an API but I don't intend to introduce any additional tools for building out an API. If I wanted to go in that direction, I would probably create a different starter kit specifically for that.

[gedw99]

thanks @mikestefanello for the feedback.

Yes I agree a different starter pack would be required.

[akhayyat]

Actually, part of the appeal of this project for me was its potential to do both: SSR and API. I'm looking for framework or a starter project that can do both: serve rendered pages for web users, and serve an API for mobile users.

Just saying that there is a place for projects that do both at the same time.

Any pointers on how to get there from pagoda, or other starting points, would be appreciated.

[gedw99]

I pointed out how using openapi and others but the anti er Mike is not up for it from what I gathered.

the problem is that it’s currently not layered in the way is needs to be and would need sone refactoring.

Abd tine is not I finite so out of luck

[mikestefanello]

There definitely is a place for a project that can do both, but the two main downsides of providing that is that it's a rather large, extra layer that I'd have to maintain, and if this project has to consider both then it becomes much harder to make decisions since you have to take both sides in to consideration and you probably have to end up making sub-par choices to satisfy both sides. I would probably want to rework a lot of the existing code and structure if providing an API. And I assume the amount of people that want both is rather small, and those that only want an API are probably not looking for a big kit like this; though those are both assumptions.

If you want auto-generated API documentation, I'd recommend trying https://github.com/swaggo/echo-swagger. I've found it really nice to work with, though that was a while ago.

With HTMX, you can certainly update parts of the DOM asynchronously. There are already plenty of examples of that provided. You just have the server return HTML rather than JSON. One of the core principles of this project, and why HTMX was chosen, was that I wasn't interested in building a web service and separate, heavy frontend that has to consume, parse and format JSON. That's also why I'm not currently interested in making this project more suitable for building APIs.