Use Task<T> as return type in IApiClientSerialization

[DiscoPYF]

IApiClientSerialization allows consumers to implement their own serialization logic, using their preferred serializer. Some libraries support asynchronous task-based operations, e.g. https://docs.microsoft.com/en-us/dotnet/api/system.text.json.jsonserializer.deserializeasync?view=netcore-3.1

We can update the signature of the methods in IApiClientSerialization to return a task and allow implementations with fully asynchronous operations.

Task<T> DeserializeFromStream<T>(Stream stream);
Task<byte[]> Serialize<T>(T item, bool useCamelCasePropertyNames, bool ignoreNullValues);

[tjoubert]

@DiscoPYF, for backward compatibility, do you think it makes sense to add the async method definitions as additional methods to the interface instead of updating the existing methods. So, we will have:

T DeserializeFromStream<T>(Stream stream);
Task<T> DeserializeFromStreamAsync<T>(Stream stream);

byte[] Serialize<T>(T item, ApiClientSerializationOptions serializationOptions);
Task<byte[]> SerializeAsync<T>(T item, ApiClientSerializationOptions serializationOptions);

string SerializeToString<T>(T item, ApiClientSerializationOptions serializationOptions);
Task<string> SerializeToStringAsync<T>(T item, ApiClientSerializationOptions serializationOptions);

What do you think?

[DiscoPYF]

@tjoubert I am seeing your message just now. The next release is gonna have breaking changes, so I think we can take this opportunity to keep the interface simple by only declaring methods that return a Task.

What about updating the interface like so:

public interface IApiClientSerialization
{
    Task<T> DeserializeFromStreamAsync<T>(Stream stream);
    Task<byte[]> SerializeAsync<T>(T item, ApiClientSerializationOptions serializationOptions);
    Task<string> SerializeToStringAsync<T>(T item, ApiClientSerializationOptions serializationOptions);
}

Then any implementation that is not using async can just add a return Task.FromResult() statement. Example:

public class JsonNetApiClientSerialization : ApiClientSerialization
{
    public override Task<T> DeserializeFromStreamAsync<T>(Stream stream)
    {
        T result = DeserializeFromStream<T>(stream);
        return Task.FromResult(result);
    }
}

Then we update the API clients classes accordingly, e.g. make ApiClientBase.GetContent use async/await. It's a bit more effort but I think it's worth keeping the serialization API simple.

For anyone who uses its own serializer implementation instead of JsonNetApiClientSerialization, it should be a one-line change.

[tjoubert]

@DiscoPYF Thanks for this suggestion. I think it makes perfect sense.