Document "<unchanged>" and "<redacted>" values for DataSourceCredentials.connectionString

[heaths]

The DataSource model requires DataSourceCredentials, but the latter model is not returned from data source APIs. Since it's required, we cannot send back null (at least, the .NET generator does not support this since it's not "x-nullable": true and is, again, authored as required) and if we send an empty value (connectionString is not required), it would either err on the server or, worse, wipe out the existing credentials stored for the data source.

Instead, I'm told, the connectionString should be set to either "<unchanged>" or "<redacted>" to avoid wiping out the credentials. These should be documented in swagger so that callers know what to pass to update a data source.

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @felixwa, @brjohnstmsft.

[brjohnstmsft]

FYI @bleroy -- Please route to the right owner

[xiangyan99]

To make sure I understand correctly, do we always set connectionString to "<unchanged>" when we see it is empty?

Or we need to distinguish it is an update operation or create operation?

If we only do it for update, how can we know it?

[heaths]

We should probably only set it to "<unchanged>" in the SDK when sending to create_or_update_data_source_connection (or equivalent for other languages; I'll use pythonic names since you asked 😉). If you already have a wrapper in your SearchIndexerClient for this method, maybe just set it to that value if it's null (in case they overwrote the value intentionally). In .NET, our serializer only ever reads from that when sending it to CreateOrUpdateDataSourceConnection so my property's get accessor sends either the overwritten ConnectionString property value or "<unchanged>", which is effectively equivalent but seemed easier to maintain (fewer instances to handle).

[brjohnstmsft]

@heaths The issue with setting it explicitly to <unchanged> in the SDK is that you don't know if you're creating or updating, as @xiangyan99 pointed out. I'm not sure the SDK needs to handle this case, given how applications are expected to use the GET-modify-PUT pattern for updating data source connection properties.

[xiangyan99]

Another option may be we set it to "<unchanged>" in GET operation. Then we don't need to do extra stuff in PUT.

[brjohnstmsft]

@xiangyan99 The service should already be doing that for you.

[heaths]

@brjohnstmsft, it's not. We have to do something, because in my testing (when I found this), .NET was sending back an undefined DataSourceCredentials model (initially, that was because of my wrapper implementation) but then an empty one (no "connectionString" property), which I was told was not okay. The swagger isn't defined in such a way that our generators would handle correctly.

@xiangyan99, that was my initial implementation idea as well, but then it actually makes the connection_string property in your API "<unchanged>", which is probably not something we should expose to the user as its an implementation detail of the service.