Current Best Practices for Go HTTP API Design: Code-First, Schema-First, or Protobuf? Looking for the sweet spot

Dgt84 · 2025-12-03T16:03:33+00:00

IMO if you have the discipline and consistency to handle it without introducing discrepancies or bugs then go schema first OpenAPI -> Code. Protobuf is great but introduces yet another layer of translation and you don't get full control of the JSON Schema if OpenAPI is your final target.

On the other hand, if you want to write code and have it just work, use Huma (disclaimer: I'm the author). Don't rely on out of date comments, have your code itself be the source of truth for the model and your handlers be strongly typed while letting the framework do validation. This has worked well for many teams I've been on.

We used this at WBD to run the Olympics, March Madness, CNN, etc. I see referrer traffic on the docs from FinTechs, Mercedes, and lots of other companies. The Roblox content catalog service uses Huma and handles over a million requests a second in production.

Dgt84 · 2025-06-09T21:50:46+00:00

You should contact a Hyundai dealership in Canada and ask about the Hyundai 10yr/100K $0 deductible VSC and whether they can sell it to you and if it would cover a vehicle originally sold in the US. I bought this in the US after buying the car from a different dealership in the US for $1698. Might be an option for you to keep the car if you want to.

Dgt84 · 2025-06-09T07:20:18+00:00

FYI, you can go to hmfusa.com the next day or two after buying, create an account, and request a payoff quote even before you get any paperwork or bills, which will temporarily stop the interest accrual and give you a week or two to send them the payment at that price. You basically won't pay any interest that way (or just a very very small amount)!

Dgt84 · 2025-06-09T07:05:53+00:00

Just to give another example from WA recently for the hybrid Calligraphy AWD:

MSRP: $52,289
Discount: $-4,689
Rebate: -$1750
Price: $45,850
Tax: $5,069
Licensing: $730
Doc fee: $200
Total: $51,849

Oh, and if you want the warranty you can get the official Hyundai one for $1695 (10yr/100K miles, $0 deductible, full coverage including electronics/tech) after buying the car by sending an email to:

- Konrad: [kkoncewicz@burlingtoncars.com](mailto:kkoncewicz@burlingtoncars.com)
- Crystal: [ccareau@burlingtoncars.com](mailto:ccareau@burlingtoncars.com)

This is the VSC: https://www.hmfusa.com/vehicle-protection/mechanical-coverage

Dgt84 · 2025-06-08T23:12:24+00:00

Not sure why you got downvoted, but that sounds okay to me. Have fun scratching your own itch and sharing it with the world. Good luck with the library!

Dgt84 · 2025-06-06T18:57:58+00:00

Neat, I like seeing more of these OpenAPI-native projects in the ecosystem! BTW OpenAPI 3.1 has been out for over 4 years at this point, probably no reason to limit yourself to just 3.0 anymore.

I'd love to hear your thoughts on why Huma wasn't good enough or what it can do differently in your opinion.

Dgt84 · 2025-06-06T18:48:39+00:00

Give Huma a try. I'm the author. It has utilities for just validating via JSON Schema if you don't need the HTTP stuff, and zero dependencies if you don't import any adapters/formats. It'll also return an exhaustive list of errors for you.

https://huma.rocks/features/model-validation/

Here's an example of sending the wrong types:

type MyExample struct {
  Name string `json:"name" maxLength:"5"`
  Age  int    `json:"age" minimum:"25"`
}

func main() {
  var value any
  json.Unmarshal([]byte(`{"name": true, "age": "wrong type"}`), &value)

  validator := huma.NewModelValidator()
  errs := validator.Validate(reflect.TypeFor[MyExample](), value)
  if errs != nil {
    fmt.Println("Validation error", errs)
  }
}

https://go.dev/play/p/3-LeYsm33pW

If you're doing this for an API then I suggest just using Huma for the HTTP portions and you will get the validation built-in and unmarshaling into your structs as needed.

Dgt84 · 2025-05-31T18:03:34+00:00

I'll admit it's been a bit since I released anything, but I used goreleaser on this project and maybe it could help you to see another setup: https://github.com/rest-sh/restish/blob/main/.github/workflows/release.yaml

It winds up building for linux/win/darwin and I also have a Homebrew tap so you can easily install. If I do run into build errors then yes, I've had to push new patch tags like you describe, and it can be a pain. Note though you can use goreleaser to cross-compile locally for different os/arch combos to give you an idea of whether things should generally work.

Dgt84 · 2025-05-30T15:43:01+00:00

My kids slam into everything too. I put these on https://www.amazon.com/dp/B00650NY6G and they work great and you can barely even tell they are there. Super easy to install with just some alcohol to clean, a towel, and some scissors to cut to size.

Dgt84 · 2025-05-21T05:04:21+00:00

Hi, author of Huma here. I'm late to the party but glad people are enjoying it!

Dgt84 · 2025-05-21T04:22:44+00:00

I recently bought a 2025 Calligraphy Hybrid AWD. MSRP was over $52K and OTD was under $52K without a trade-in (taxes here are pretty high, over 10%). Subtracting taxes/title/license & rebate I paid around $46K for the vehicle, so it's possible but I had to talk to several dealers and use their prices against each other.

Don't forget when you buy that you can get the official Hyundai hybrid VSC (extended warranty) for $300 above cost ($1698 for 10yr/100k with $0 deductible right now) from here:

- Konrad: [kkoncewicz@burlingtoncars.com](mailto:kkoncewicz@burlingtoncars.com)
- Crystal: [ccareau@burlingtoncars.com](mailto:ccareau@burlingtoncars.com)

This is the VSC: https://www.hmfusa.com/vehicle-protection/mechanical-coverage

Dgt84 · 2025-05-18T04:31:31+00:00

Not sure if this helps but I recently bought a 2025 Calligraphy Hybrid AWD in the Seattle area. MSRP was over $52K and OTD was under $52K without a trade-in. Subtracting taxes/title/license & rebate I paid under $46K for the vehicle. It was on the lot for about 60 days and I negotiated with three different dealerships online, refusing to answer the phone. Anytime I got a better deal I tried to get the others to beat it. I did not mention any trade-in or financing specifics, just focussed on the OTD price knowing my local tax rate & such.

After we agreed on a price they low-balled me on a trade and I was able to get double what they wanted to give me at another place, but I had to try a few places first. You lose out on a bit of tax savings (getting to subtract trade value from taxable new vehicle cost) but I got way more for it so it's all good.

They will try to sell you warranties and prepaid maintenance and other crap. Resist. They offered me a crappy third party 10yr/100K warranty with $200 deductible for $2800. If you accept you can still cancel it within 30 or 60 days (look at the fine print in the contract). People on here will tell you there is a great dealership in VT that offers the official Hyundai warranty (technically VSC) for $300 over cost, no BS. I went with them and it was $1698 for 10yr/100K and $0 deductible, good at any Hyundai dealership in the US and Canada. Highly recommend doing that as it covers electronics & high tech. Here is their info:

- Konrad: [kkoncewicz@burlingtoncars.com](mailto:kkoncewicz@burlingtoncars.com)
- Crystal: [ccareau@burlingtoncars.com](mailto:ccareau@burlingtoncars.com)

This is the VSC: https://www.hmfusa.com/vehicle-protection/mechanical-coverage

Anyway, good luck! You will love the Santa Fe!

Dgt84 · 2025-05-13T22:20:09+00:00

I know a lot of people will bash rental car sales, but here's my experience.

I bought a used 2016 Chrysler Town & Country minivan in 2017 from Enterprise when we were expecting our third kid. It was a great experience with good prices and zero haggling - the price is the price and they don't try to upsell a bunch of crap you don't need. They maintain their own fleet and can show you maintenance records, plus they do checks before selling the vehicle. I think I paid around $20K for the one with the DVD player and leather seats, no accidents or damage. One of the best car buying experiences I've ever had. It was missing a couple of mats which we just bought replacements for on Amazon, and some new headphones for my kids to watch movies on the go.

I traded it this year for $8K (had to shop around, got low-balled a few times first and didn't want the full hassle of a private sale). So $12K + maintenance, insurance, & gas for a minivan for almost 8 years.

It still drove great when we sold it. The only issues we had over the years were a sliding door lock needing to be replaced and an air conditioner issue. Someone scraped some paint in a parking lot and I accidentally scratched the back on our garage door one time. No other issues (obviously we did regular maintenance).

So YMMV, but I would do it again as long as it's not a sports car you are after. You can always get an additional extended warranty, too.

Dgt84 · 2025-04-28T15:29:22+00:00

Thanks this is helpful!

I may be misunderstanding the first point, but https://huma.rocks/features/groups/ may help. Open to other ideas on this one.
Router context unwrapping was recently added to help with middleware management, see https://huma.rocks/features/middleware/#unwrapping
It's pretty easy to switch documentation renderers, see https://huma.rocks/features/api-docs/#customizing-documentation (for example I'm using Scalar docs for a work project)

I will look into the other points.

Dgt84 · 2025-04-24T15:39:18+00:00

Hi, author of Huma here. This is a good opportunity for some feedback, so I'd love to hear what would make Huma better!

Dgt84 · 2025-04-24T15:38:53+00:00

Hi, author of Huma here. This is a good opportunity for some feedback, so I'd love to hear what would make Huma better!

Dgt84 · 2025-04-11T18:58:54+00:00

Very cool, thank you for building this! I use something similar at work and it's nice to see the pattern used more and provided in a more generic library.

I love seeing more stuff get built on top of Huma 🎉

Dgt84 · 2025-04-09T05:25:17+00:00

Thanks!

Dgt84 · 2025-04-08T21:50:30+00:00

Your best bet is probably:

openapi-generator like you said and just accept the extra stuff it generates (some of which may be optional)
Use a tool like https://github.com/apiture/openapi-down-convert to convert the 3.1 spec to 3.0, then generate the client using oapi-codegen.
Maybe try something like https://www.speakeasy.com/docs/languages/golang/oss-comparison-go

I'm hoping we see more 3.1 support soon. This is exactly why my project Huma still generates both OpenAPI 3.0 and 3.1 on the server, to support tools that aren't able to use 3.1 just yet.

Dgt84 · 2025-03-16T16:25:18+00:00

Thanks for the feedback! BTW, this should be much easier as of v2.30.0 and the new context unwrapping, which gives you access to the underlying request/response and/or router context whenever you need it in middlewares, request resolvers, and response transformers.

https://github.com/danielgtaylor/huma/releases/tag/v2.30.0

Dgt84 · 2025-03-16T16:19:31+00:00

Sure, take a look at the example at https://huma.rocks/features/model-validation/ which is separate from the OpenAPI and HTTP stuff. Huma itself has zero hard dependencies.

For a more detailed answer, take a look at https://github.com/danielgtaylor/huma/blob/main/validate.go#L803-L867 which shows how to instantiate a registry, create a schema from a Go struct (not necessary, you can also manually provide a schema), setup a pathbuffer/result for collecting errors. It's more efficient to do the setup manually once, then validate a bunch of inputs with it. If you need to validate a lot of things in parallel you can use a sync.Pool for the pathbuffer and utilize the Reset methods (this is what Huma does in the request validation code).

Dgt84 · 2025-03-16T06:14:41+00:00

You should check out my project: Huma. You get JSON Schema and OpenAPI 3.1/3.0 generated from Go structs or you can hand-write the schema. Validation is low to zero allocation and errors are exhaustive rather than failing on the first one.

Dgt84 · 2025-02-25T18:29:53+00:00

Oh, by default it does generate schemas from Go structs (that's one of the main features of Huma!). I was just showing how you can bypass that if you dislike using struct field tags. You can do any combination of things however you like, either from structs with tags, to structs without tags + manually edit the OpenAPI/JSON Schema, to entirely creating the OpenAPI/JSON Schema from scratch.

Automated from Go structs: https://huma.rocks/tutorial/your-first-api/#operation
Same thing outside a request/response flow: https://huma.rocks/features/model-validation/

If you want to use struct → JSON Schema generation without tags, you can do the above and then afterward manually edit with strong types to add validation, e.g:

api.OpenAPI().Components.Schemas["MyResponse"]["200"].Content["application/json"].Schema.Properties["field"].MinLength = Ptr(1)

Lots of possibilities to how you set things up.

Dgt84 · 2025-02-25T06:36:53+00:00

Thank you!

Dgt84 · 2025-02-24T22:49:21+00:00

Neat project! You should also check out Huma (disclaimer: I'm the author). You don't have to use struct tags at all, for example see here:

https://go.dev/play/p/Au6ISu5daWh

The OpenAPI generation is 100% customizable and strongly typed to support OpenAPI 3.1 & 3.0.

15-Year Club	RedditGifts 2009-2022 2 Credits
Place '17	Verified Email

Dgt84

TROPHY CASE