It is ok to experiment. Usually codebases with a history need standards and rules to speed up collaboration and more in general to facilitate growth.

Some of those are enforced at the language or community level via formatter, linters. Others get introduced step by step from previous contributors.

An API handler needs to have a page argument if it supports pagination. The context or scope needs to have a AuthToken set.

Those abstractions enable writing collaterals like utility functions for testing.

But it is reasonable to try new approaches. Recently I reviewed how I write HTTP API in Golang and I noticed that all the pros that I thought OpenAPI was providing to myself and my environment didn’t have the desired effect. Those pros are still valid, but they didn’t work with my teammate and for myself, in the latest three projects I used OpenAPI.

Now what do I do? A major rewrite is a waste of time for the company and for myself. It does not add anything to the product even if I feel it will make my happier and more productive. For sure the first, can’t prove the second.

The thing I needed to do was to find a way to inject a new approach of writing HTTP APIs alongside the current one to enable myself and the team to keep supporting the current handlers like they are but write new one differently to figure out a way that makes us ok to keep working with this codebase.

With HTTP API in Go the solution is pretty simple, we have routers that can be used to register handlers and the handler interface is adopted almost everywhere because it is provided by the standard library.

Now that I am a few months into this hybrid approach I can tell you about a side effect that I didn’t plan for. We moved at our own time handlers off OpenAPI as part of writing new features or during a bugfix, and I am confident that we will be able to get to OpenAPI free codebase in a few more weeks without having to plan for it.

Another effect of such unplanned deprecation is that we touched handlers and were written during prototyping and didn’t have test coverage or a good layer of composition. Developers took the extra mile of adopting abstractions that were not there at the time those handlers were written, and the result is a much stronger and fresh codebase.