Update from v5-v6 migration plan is lacking important information

pdubb29 commented 2 years ago

Describe the bug?

Lacking information includes, but is not limited to

Migration docs do not contain a definitive date when v5 is fully retired. It simply says "retiring"
Classes and methods marked as obsolete in the previous nuget package version [5.6.2]
- Consider releasing a minor version that marks these as obsolete
Missing classes (Resource) that are not mentioned in the migration document.
No guidance on the new way of doing dependency injection
- Separation of one globally initialized client into multiple.
With your upgrade to RestSharp, how are errors handled? Previously, this was accomplished by catching exceptions (OktaApiException) and reading the exception message. How is it handled in RestSharp? Are you still throwing exceptions when you RestSharp returns a non-success status code?

What is expected to happen?

Should be easy to migrate with a migration guide.

What is the actual behavior?

Reading the documentation doesn't provide a lot of information about classes that have been removed/renamed.

I'm having to download the source code and compare the classes that are given in order to fix it.

Reproduction Steps?

Download v5.6.2 of the Okta.Sdk nuget package Write an extensive application implementing v5.6.2 code. Write unit tests to support said extensive application. Upgrade to v6.0.0 of the Okta.Sdk nuget package

Observe all the errors shown.

Additional Information?

No response

.NET Version

.net core 3.1 latest

SDK Version

5.6.2 -> 6.0.0

OS version

No response

ddevoogt commented 2 years ago

We need to know how to prioritize this. A timeline would be great!!

laura-rodriguez commented 2 years ago

Hi @pdubb29 and @ddevoogt , Thank you so much for your feedback!

We'll review your suggestions and update our docs accordingly.

In the meantime, you might wanna check the API reference docs that provide additional information on the client usage here. You can click on a specific API and get more details on the implementation; for example, see this link.

Internal Ref: OKTA-549376

pdubb29 commented 2 years ago

Any reason in particular why there were so many changes?

Instead of keeping the exception behavior the same, you've now changed the class name and constructors, and underlying exception details.
Why do we still not have a definitive retiring date for v5? Would this version of the library continue to function even though you wouldn't support it? Or is the underlying api change a requirement for this change?

In short, we've had to do multiple waves of changes,

Update namespace and classes to new ones. (600+ errors)
Update Dependency Injection.
Update Unit Tests to support current expected behavior.
Expected behavior when errors are encountered on the Api has now changed. (Example: Used to be OktaApiException was thrown, now it's ApiException) which we had to discover through running the api and testing. Couldn't have this be included as part of the migration guide?

laura-rodriguez commented 2 years ago

Hi @pdubb29,

We acknowledge that migrating from v5 to v6 will require considerable effort, but we expect this change to benefit our customers in the long term.

In previous versions, we used an OpenAPI v2 specification with many custom attributes and vendor extensions that required us to implement a custom client generator that should work for all the languages we support. Our process to release support for new APIs and endpoints could have been better since, most of the time we needed to add new APIs, the generator required some adjustments to support new attributes added to the spec. This process caused delays in releases that could be available for our customers sooner.

With OpenAPI v3, we saw an opportunity for improvement in several areas:

We can provide an API specification that follows the OpenAPI v3 standard and eliminate custom attributes and vendor extensions.
Given that now our specification is compliant with OASv3, we can use well-known generators used and maintained by the community. In this case, we chose openapi-generator.tech.
Given that we eliminated custom attributes, we can speed up our release process and let our customers access new APIs sooner. Also, everyone will have access to the OpenAPI specification and will be able to generate their own clients in other languages of their choice.

That being said, we're going to improve our migrating guide and provide updates about support for v5 soon based on the valuable feedback on this thread, and please keep helping us to improve it. I hope this brief context makes sense to you and be beneficial in the long term.

laura-rodriguez commented 1 year ago

Hi Everyone,

Thank you for your patience and feedback. We have updated the migrating guide and the support dates for series 5.x. Feel free to reopen if something's missing.

okta / okta-sdk-dotnet