Show me your API • The Applied Go Weekly Newsletter 2024-08-11
Your weekly source of Go news, tips, and projects
Humans love to communicate, and likewise does the software they create. To communicate over a distance, humans use telephones, email, or text or video chat, while software uses REST APIs (among other options). The OpenAPI standard facilitates reasoning about APIs by providing a formal specification language. The Go Time episode in the Podcasts section above inspired me to create a list of OpenAPI tools and frameworks for Go in the Go Tip section.
But first, let's talk about something unique, something functional, and something skill-advancing. (In the Featured Articles section.)
Featured Articles
Reduce allocations and comparison performance with the new unique package in Go 1.23 - Joseph Woodward | Software Engineer & Go lover based in Somerset, England
Something "unique" is coming with Go 1.23: The unique package. By canonicalizing (aka "interning") comparable values, it helps reduce allocations, memory footprint, and the cost of comparing values. Joseph Woodward demonstrates unique's benefits.
What Would it Be Like to Do Functional Programming in Go? | nyadgar.com
No, the author does NOT try to shoehorn foreign programming paradigms onto Go. Rather, for the fun of it, he implements several functional programming concepts from Haskell in Go.
Stream: Go 10 Week Backend Eng Onboarding
Stream reveals their 10-week onboarding program for new Go devs.
Podcast corner
OpenAPI & API Design with Jamie Tanna (Go Time #328)
Jamie Tanna, one of the maintainers of oapi-codegen, joins Kris and Johnny to talk about OpenAPI (of course), code malleability, README-driven development, and why you should not use a spoon to eat ice cream!
📊 While we wait for Go 1.23, we discuss the latest Stack Overflow survey results
The StackOverflow developer survey revealed some bad vibes within the developer community. (See the "Unrelated" section in the previous issue.) Jonathan and Shay discuss the results, but not before talking about the new Go minor releases and a proposal to add Context to testing.T that is probably going to be accepted.
Go tip of the week: 4 tools for generating REST APIs
No REST API without an OpenAPI documentation! OpenAPI enables users of your API service to generate client code in the languages they use. But managing your API server code and an OpenAPI spec simulaneously is time-consuming and error-prone.
Here are four options for cutting that effort in half, by either generating Go code from an API spec, or generating an API spec from Go code.
From OpenAPI spec to code
Usually, you'd want to write the spec for your API first and then generate the code from the spec. Why? Because an API requires both server and client code, and moreover, you might want to enable software written in other languages than Go to connect to your API.
Two of the four contenders are spec-to-code generators:
oapi-codegen/oapi-codegen: Generate Go client and server boilerplate from OpenAPI 3 specifications
oapi-codegen is the oldest of the four tools but still up to date with changes like the new net/http featuers in Go 1.22. A main goal of oapi-codegen is to make building a server a straightforward process. To achieve that goal, oapi-codegen supports popular server packages like Chi, Echo, Fiber, or Gin.
ogen-go/ogen: OpenAPI v3 code generator for go
ogen's unique selling points include lack of reflection or empty interfaces in the generated code, as well as pointer-free handling of optional, nullable, and optional nullable fields, using generics-based wrappers instead.
From code to OpenAPI documentation
There are good reasons for writing Go code first and generating the OpenAPI spec from the code. A compelling advantage is that your Go code becomes the single source of truth. Moreover, you can use the language you are already familar with, instead of learning Yet Another Specification Language™.
These two Go frameworks support you with going from Go code to a generated OpenAPI spec:
go-fuego/fuego: Golang Fuego - web framework generating OpenAPI 3 spec from source code
Fuego is a web server framework. (Think "Gin", "Chi", or "Echo".) All you do is write an API server with Fuego, and the final Fuego server then delivers a generated OpenAPI spec at /swagger/index.html. It's that simple. Fuego supports all net/http-compatible middleware.
Your First API - Huma
Huma neither promotes API-first nor code-first approaches. Rather, it's "Huma-first". Sounds strange, but the idea is intriguing: You write an API code skeleton in Go, then Huma generates both the OpenAPI spec and the Go boilerplate for you. All that's left to you is implementing the handlers. Like Fuego, Huma serves the OpenAPI spec at a specific URL. Unlike Fuego, Huma is web framework agnostic and lets you use a router of your choice.
Whatever you choose, there is nothing to lose
All of the above tools and frameworks have tested and proven concepts, and while the philosophies and approaches differ, I'd reckon that you'd be able to write solid REST API apps with any of them. Large, multi-language projects surely want to go the API-spec-first route while pure Go projects may prefer using Go code as a starting point.
Whatever approach and tooling you choose, may the source be with you!
Quote of the Week: Go will get you there
Go is proof that simplicity, being highly portable, having exceptional package management concept, built-in tools, and a good ecosystem are integral parts of what makes a programming language useful. When you need to get things done, Go will get you there quickly.
More articles, videos, talks
How Go Arrays Work and Get Tricky with For-Range
A "deep-dive intro" to Go arrays, the less popular cousins of slices.
So, you’re splitting strings on the hot path
A short analysis of the allocation behavior of Go's strings.Split and bytes.Split, and of C#'s string.Split.
Go 1.22.6 and Go 1.21.13 are released
From the release notes: "go1.22.6 (released 2024-08-06) includes fixes to the go command, the compiler, the linker, the trace command, the covdata command, and the bytes, go/types, and os/exec packages."
All fixes are listed in the Go 1.22.6 milestone.
Downloads available as usual at go.dev/dl or through your favorite OS packet manager.
JSON vs FlatBuffers vs Protocol Buffers
Go and JSON... oh well. It's not a great story and never has been. Go's strict typing clashes with JSON's sloppiness, and performance expectations often remain unmet due to the effort of serializing and parsing JSON.
Two alternatives exist (if we ingore the gob package from the standard library, which is specific to Go): FlatBuffers and Protocol Buffers.
But which one to pick? Elton Minetto compared their performance in various aspects.
Building BLE Applications with BleuIO and Go - BleuIO - Create Bluetooth Low Energy application
Tired of writing backend code? Try coding a Bluetooth Low Energy app for a change!
Projects
Libraries
Files · main · ghtmx / ghtmx · GitLab
A framework for a framework? Sure, why not. If the original framework is for web pages and the on-top framework is for the backend, it makes totally sense.
go-htmx aims at creating web apps in Go easier by modeling a web page as a data structure with control elements and event handlers.
Promised advantages include reduced HTML writing, type safety, speed improvements through partial loads, and more.
GitHub - korsajan/gocatboost: GoCatBoost is a wrapper for the CatBoost library, enabling the use of CatBoost in Go.
"CatBoost is a machine learning algorithm that uses gradient boosting on decision trees." Unfortunately, it is written in Python (well, unfortunately for non-Python users, that is). Gophers now can access CatBoost through the GoCatBoost package.
GitHub - meshapi/go-shutdown: Lightweight Go package to handle process terminations and shutdowns gracefully.
Terminating an app the hard way can lead to data loss. With this package, you can set up a pipeline of operations that execute when the process receives the SIGTERM signal.
Tools and applications
GitHub - Achno/gowall: A tool to convert a Wallpaper's color scheme / palette
So your favorite wallpaper does not quite match the color theme of your UI? No problem, gowall irons out the differences.
GitHub - plutov/formulosity: Self-hosted Surveys as Code platform.
Not keen on depending on a survey service? Host your own!
GitHub - ErikKalkoken/janice: A desktop app for viewing large JSON files.
If you need to inspect large JSON files frequently, you might appreciate the speed and convenience of Janice, a Fyne desktop app for Linux, macOS, and Windows.
GitHub - valyentdev/ravel: An open-source microVMs orchestrator.
Brand new, still ripening on the tree, but holy moly, the roadmap is promising!
(Side note: Vaylent's Alexis Bouchez wrote the article "Build Your Own SMTP Server in Go" featured in the previous issue.)
GitHub - julien040/anyquery: Query anything (JSON, CSV, GitHub, Notion, Airtable, etc.) with SQL
A CLI (and a Go library) that can run SQL queries on virtually anything except the Voynich manuscript.
Completely unrelated to Go
Things you can do with codebases
How do you start working on an existing open-source project? Fix some bugs, improve the docs? How boring!
Thorsten Ball lists more than a handful of ways to tinker with a codebase for fun and learnings.
HTTP requests via /dev/tcp
Now, THAT's one neat trick! Did you know that you can have a Bash script make HTTP GET requests by... writing to /dev/tcp? No curl or wget required, just two standard Unix commands and a built-in command.
Happy coding! ʕ◔ϖ◔ʔ
Questions or feedback? Drop me a line. I'd love to hear from you.
Best from Munich, Christoph
Not a subscriber yet?
If you read this newsletter issue online, or if someone forwarded the newsletter to you, subscribe for regular updates to get every new issue earlier than the online version, and more reliable than an occasional forwarding.
Find the subscription form at the end of this page.
How I can help
If you're looking for more useful content around Go, here are some ways I can help you become a better Gopher (or a Gopher at all):
On AppliedGo.net, I blog about Go projects, algorithms and data structures in Go, and other fun stuff.
Or visit the AppliedGo.com blog and learn about language specifics, Go updates, and programming-related stuff.
My AppliedGo YouTube channel hosts quick tip and crash course videos that help you get more productive and creative with Go.
Enroll in my Go course for developers that stands out for its intense use of animated graphics for explaining abstract concepts in an intuitive way. Numerous short and concise lectures allow you to schedule your learning flow as you like.
Christoph Berger IT Products and Services
Dachauer Straße 29
Bergkirchen
Germany