Skip to main content

github.com/kataras/iris as the API framework

Timeline​

TimeDescription
2022-12-22 14:00:00Created
2023-01-02 12:00:00Accepted

Status: Discussion​

Context​

The Archipelo APIs are currently implemented using the standard net/http library, github.com/go-chi/chi for routing and some custom code.

While this solution has worked so far, it has room for improvement.

Mainly, we want to replace the custom code used to wrap the HTTP handlers which is based on reflection. While this solution gave us some flexibility regarding how we define HTTP handlers, reflection should be avoided when possible because it is slower than normal code, and harder to read and maintain.

An example of such a complex code can be seen in api.go

Because of this flexibility, our HTTP handlers can also be defined using different signatures. We want to change that and have a single consistent signature for all handlers of our API. Having a single format allows for easier routing reorganization with the minimum code change.

Some of our custom middleware are based on an unmaintained library. For example, the csrf package is using github.com/gorilla/csrf which belong to the Gorilla toolkit that has recently been archived.

We also want to introduce new features like automatic API documentation.

For all these reasons we want to pick a new API framework.

The requirements for it are:

  • Actively maintained
  • Open-source
  • Avoid reflection
  • Consistent handler signature with possible integration with the standard net/http.Handler interface
  • A rich catalog of middleware
  • Routing algorithm as fast or better than github.com/go-chi/chi

Other Considerations (from Slack)​

The alternatives for Iris would be other all-in-one web frameworks:

The quick answers to "why not?":

  • Gin: while it is the most popular one, its performance is slower than other 4 frameworks based on many benchmarks. Also, I was using it previously and it has issues with wildcard routes and there are a lot of people who had the same issues. We're not using them at the moment, but we don't want to pick something knowingly that there are issues.
  • Fiber: the fastest one, BUT it is based on fasthttp package that is not compatible with the standard net/http library. It will require more effort to migrate and even use it. The fasthttp package is created for edge cases when you care for each and every millisecond, so I think it is overkill for our case.
  • Echo: its community is the smallest among the 4 frameworks, while everything else is pretty much the same.

Decision​

After research, our decision is to introduce github.com/kataras/iris/.

Does it meet requirements?

  • Actively maintained: The repository is alive and commits are made nearly daily.
  • Open-source: BSD-3-Clause license
  • Avoid reflection and consistent handler signature: Handlers are based on a statically-typed signature and reflection is only used for debugging purposes.
  • Rich catalog of middleware: iris comes with a rich library of built-in middleware and the community has also created a lot of extra plugins and extensions: https://github.com/iris-contrib
  • Routing algorithm as fast or better then github.com/go-chi/chi: Here are some routing benchmark results:
BenchmarkIris/static-8             24915             43438 ns/op            2268 B/op         40 allocs/op
BenchmarkIris/GithubAPI-8          10317            102407 ns/op           16156 B/op        677 allocs/op
BenchmarkIris/GplusAPI-8          239486              4583 ns/op             662 B/op         32 allocs/op
BenchmarkIris/ParseAPI-8          144165              7152 ns/op             773 B/op         38 allocs/op
BenchmarkChi/static-8              20630             60061 ns/op           48868 B/op        471 allocs/op
BenchmarkChi/GithubAPI-8           12314             86211 ns/op           63499 B/op        609 allocs/op
BenchmarkChi/GplusAPI-8           293467              4136 ns/op            4035 B/op         39 allocs/op
BenchmarkChi/ParseAPI-8           144230              8578 ns/op            8073 B/op         78 allocs/op

Consequences​

  • Usage of an up-to-date and supported framework
  • Consistent way of writing any API
  • Possibility to automatically generate swagger documentation
  • Better performance

The migration to iris can be done gradually and does not requires a complete rewriting of all our API immediately. We can wrap our existing code to make it compatible and use iris directly for any new API we create.