This release publishes the existing V2 API under a separate module.
The existing API package will remain available for backward compatibility reasons,
but new features will only be added to the new module.
Usage
Although Dex remains backward compatible and continues to provide the API under the original location,
we highly recommend replacing it with the new location in your project (if you use the official API package):
go get github.com/dexidp/dex/api/v2@v2.0.0Then replace every occurrence of github.com/dexidp/dex/api with github.com/dexidp/dex/api/v2 in your code.
Finally, make sure to get rid of the main Dex module dependency:
go mod tidyWe also recommend using the new API module instead of manually downloading the proto and generating client stubs using protoc.
Read more about the reasons below. (tl;dr: certain future changes might break backward compatibility for these consumers)
History
Dex V2 came with a major rewrite of its API using gRPC and Protobuf.
Consumers of this new API generally followed one of two paths in their applications:
Many users imported the github.com/dexidp/dex/api package directly.
While this worked quite well for most of the time,
it introduced a dependency between consuming projects and the main Dex module itself (with all of its own dependencies).
Sometimes this caused conflicts with other dependencies of the project (aka. dependency hell).
Using Dex this way also forced us to remain backward compatible in a bunch of other areas.
To solve the dependency problem, many consumers decided to download the single proto file from the repository
and generate client stubs themselves. This turned out to be a great alternative to importing the whole Dex project
(just to use its generated API package).
Changes in Protocol Buffers
For quite some time, we wanted to break this status quo.
We tried to steer users away from importing Dex and recommended generating stubs instead.
Ultimately, the recent changes introduced in the Protobuf V2 API for Go lead us to our current solution.
Namely, the new requirement of having a go_package directive in every proto file basically forces us to provide a package with generated code and
makes code generation on the consumer side nearly impossible. (Obviously, someone can hack around this limitation, but it can't be solved nicely)
Although this requirement does not affect us at the moment, since we still use the V1 API for Protobuf,
in the future we might want to upgrade to the new API. So we decided to find a better, official place for the Dex API that consumers can use
without depending on the Dex project itself.
Dedicated API package
We spent some time with experimenting, trying to find the best possible option.
We wanted to find a solution that's backward compatible, but also fits into our future plans with Dex.
After a few iterations, we ended up creating a new package under the original API package, called /v2 and we made it a separate Go module.
This allows us to keep the API close to the main project and lets consumers import the API without the rest of Dex's dependencies.
The first tag of this package is v2.0.0 and we intend to keep versioning this package, separately from the main Dex project.
When adding new features to the API, we will tag new minor versions. Breaking changes will result in a new major version of the API,
which may also result in a major Dex version, but that's still in the future.
Thanks to protobuf's backward compatibility (and our BC promise for the API),
you should be able to talk to Dex with older API versions (compared to the one compiled into Dex itself),
but we recommend using the same version. Although the proto itself should be backward compatible,
the API package depends on gRPC, which is (unfortunately) known to break things between different versions
(thanks to the relatively large shared library).
Future of Dex's API
We have plans to extend the API with new features. Most of them should be backward compatible changes,
so they will likely be added to the v2 API.
That being said, there are a bunch of changes that will break backward compatibility and as such, will require a v3 release.
Although we know it will happen, we don't have it on our near term roadmap. Whether the v2 and v3 will coexist or not is still undecided,
but there is a chance they can.
If you have any questions related to this release, feel free to open an issue or reach out on the #dexidp
channel in the Kubernetes Slack workspace.