Initial GA work for digital twins

[timtay-microsoft]

Regenerating the protocol layer and adding the generated options classes to our convenience layer APIs

Also removing the local copy of the swagger that we had, now that the digital twins GA swagger is in the rest specs repo

[timtay-microsoft]

By declaring these as custom types, they are moved to the appropriate namespace so that we can use them in our convenience layer APIs. Note that some options classes aren't here on purpose since we have to create wrapper classes for some of them instead in order to add more options to them

[timtay-microsoft]

We no longer need a wrapper class for EventRouteListOptions, so the the converter from wrapper to generated is no longer needed

[timtay-microsoft]

This field became mandatory in the latest swagger, so it is taken in at constructor time only

[timtay-microsoft]

We get this type generated for free, so no need for this manually defined type anymore

[timtay-microsoft]

We get this type generated for free, so no need for this manually defined type anymore

[abhipsaMisra]

so we are defaulting options to null? is there a scenario where we would want these options to have a default value instead?

[timtay-microsoft]

Since they are optional, it is always allowed. It saves us from instantiating new options classes on each call. I didn't see any particular cases where it made more sense to create a default options object instead.

[abhipsaMisra]

If "null" is the expected value, then yes, I like leaving it as is. I was thinking of the scenario where we have some request Id in options, which we would want to have a default value, rather than null. But if that is not relevant for our API calls, then what we have is good.

[abhipsaMisra]

q - do we have the update operations util from azure-core available for us to use here?

[timtay-microsoft]

It is still in azure core's experimental package, so not yet. Hopefully they will have it out before we GA though

[abhipsaMisra]

q - what is the default value of OffsetDateTime?

[abhipsaMisra]

this feels like another parameter that we should send a default value (current timestamp), if the user doesn't supply a value

[timtay-microsoft]

OffsetDateTime.now(ZoneOffset.UTC);

[timtay-microsoft]

It's possible that we could make the default value null, and just not send that header though

[abhipsaMisra]

Oh, I actually prefer sending the current time as default value. Why do you feel sending null is better?

[timtay-microsoft]

I prefer sending the timestamp header with the default value by default, not omitting the header. The current implementation sends the timestamp by default. The only value I'd see in not sending the timestamp by default is to save on bytes over the wire

[abhipsaMisra]

Sure, but for this case, I'd say that the timestamp information is valuable. My vote is to send the current timestamp, if user doesn't provide it.

[timtay-microsoft]

Then I'll keep the implementation as is. If the user passes in a null options object, we will send the current timestamp for them

[abhipsaMisra]

Do we call out these error types in our CL? They might be helpful for customers, since they get a list of expected errors. Might be worth adding a link to any documentation that the service team maintains.

[timtay-microsoft]

We don't explicitly call these out in our CL, which does feel odd considering the swagger has that information. I'm not sure what the appropriate way to call this out would be. I'd rather not copy the comments from the PL into the CL since they would get out of date quickly

[abhipsaMisra]

Yeah, maintaining copies is definitely cumbersome. We could ask the service team to upload this info to some MS doc, which we could link from our CL. (if they haven't already). They might not want to maintain this solely in a swagger doc anyway.