Modifications to the API interface are a breaking change

[atc0005]

Recent changes to the API interface

• Addition of the SetHTTPClient() method
• Addition of the SetUserAgent() method

v2.4.2 and v2.5.0 included other changes to the API interface:

• Addition of the SkipWebhookURLValidationOnSend() method
  • signature of SkipWebhookURLValidationOnSend(skip bool)
• Change of the SkipWebhookURLValidationOnSend() method
  • signature of SkipWebhookURLValidationOnSend(skip bool) API
• Addition of AddWebhookURLValidationPatterns() method
• Addition of ValidateWebhook() method

Documentation

From https://go.dev/blog/module-compatibility:

Sometimes, new features require changes to publicly-exposed interfaces: for example, an interface needs to be extended with new methods. Directly adding to an interface is a breaking change, though—how, then, can we support new methods on a publicly-exposed interface?

The basic idea is to define a new interface with the new method, and then wherever the old interface is used, dynamically check whether the provided type is the older type or the newer type.

In short, recent changes to the API interface are not considered to be backwards compatible.

Prior breaking changes

Since the changes for #68 and #93 have been part of the library for nearly a year, I believe that it would cause more problems at this point to move those changes to a different variation of the API interface in order to maintain strict V2 compatibility. So would "retconning" the changes and moving them to a V3 branch or some other workaround.

Instead, we can do better going forward, both for the lifespan of V2 and the eventual V3 which can focus on a better, more cohesive package design.

Resolution

The changes for #134 and #135 however are new and not part of a public release, so that functionality can be pulled or implemented differently before a public/stable v2.7.0 release. I'm leaning towards pulling the functionality for the short-term.

Next steps

A real challenge in the current package design is that it exposes the API interface instead of a concrete type. In order to expose the functionality added by #134 and #135, we'll need to expose the "client" (renaming teamsClient to TeamsClient) or provide a new variation of the API interface (e.g., APIv2).

Not sure which is a better fit. I'm working towards implementing larger changes for #127, so will continue prototyping until a clear(er) design surfaces.

References

• Allow setting user agent, fallback to project-specific default value #134
  • 26ac7b4
• Allow overriding default http.Client #135
  • 884e59f
• Make URL validation optional #68
  • b903c06
• Better webhooks validation #93
  • 1fd45aa

[atc0005]

Next steps

A real challenge in the current package design is that it exposes the API interface instead of a concrete type. In order to expose the functionality added by #134 and #135, we'll need to expose the "client" (renaming teamsClient to TeamsClient) or provide a new variation of the API interface (e.g., APIv2).

Not sure which is a better fit. I'm working towards implementing larger changes for #127, so will continue prototyping until a clear(er) design surfaces.

Work is progressing well in this area. I hope to have local changes merged into the current prototype branch by the end of the week so I can start polishing it and preparing an alpha release for feedback in the near future.

[atc0005]

Considering the changes in #151 to be good enough for now. Further work on exposing the underlying teamsClient type will be handled by another GH issue/PR.