feat: adding a fluent interface to the SDK

[StevanFreeborn]

Introduction

The current C# SDK provides great functionality for developing applications that can interact with the Onspring API.

However, one design pattern that I find helpful and enjoyable to build with in other libraries is a fluent API. Similar to those found in libraries like:

• MSGraph SDK

var user = await graphClient.Me.GetAsync();

• FluentAssertions

var numbers = new[] { 1, 2, 3 };

numbers.Should().OnlyContain(n => n > 0);

• Entity Framework Core

var blog = db.Blogs.OrderBy(b => b.BlogId).First();

And I think that our own SDK's usage could be improved with the addition of a fluent interface. A fluent interface allows developers to chain method calls together which can make for more readable and expressive code as well as improve the discoverability of our SDK.

Benefits

• Improved Readability: A fluent interface enables developers to create code that reads like a natural language sentence. This makes the SDK more accessible and easier to understand. For example:

var filePath = "C:/temp/logo.png";
var fileStream = File.OpenRead(filePath);
var fileName = Path.GetFileName(filePath);

// Without fluent interface
var saveFileRequest = new SaveFileRequest
{
    FieldId = _fieldId,
    RecordId = _recordId,
    FileStream = fileStream,
    FileName = fileName,
    ContentType = "image/png",
    ModifiedDate = DateTime.UtcNow,
    Notes = "Test file."
};

var saveResponse = await _apiClient.SaveFileAsync(saveFileRequest);

// With fluent interface
var saveResponse = await _apiClient
    .CreateRequest()
    .ToAddFile()
    .ToRecord(1)
    .InField(1)
    .WithName(fileName)
    .WithStream(fileStream)
    .WithType("image/png")
    .WithNotes("This is a test file")
    .WithModifiedDate(DateTime.UtcNow)
    .SendAsync();

• Improved Discoverability: Developers can easily see the available methods and their order, reducing the learning curve. This I think could be particularly helpful for developers working with our SDK for the first time.

• Reduced Errors: Chaining methods in a fluent interface reduces the chances of missing a step or parameter, leading to fewer runtime errors.

Implementation

The existing OnspringClient, request models, and response models provide all the necessary structures to send and receive data to and from the Onspring API so we would still leverage these existing structures, but expose them through additional interfaces and models that provide the structure for a fluent API.

Example Usage

// Creating a request with the fluent interface
var apiResponse = await _apiClient
    .CreateRequest()
    .ToGetRecords()
    .FromApp(_appIdWithRecords)
    .ForPage(pagingRequest.PageNumber)
    .WithPageSize(pagingRequest.PageSize)
    .WithFieldIds(new[] { 1, 2, 3 })
    .WithFormat(DataFormat.Formatted)
    .SendAsync();

// Or using an action delegate for optional params
var apiResponse = await _apiClient
    .CreateRequest()
    .ToGetRecords()
    .FromApp(_appIdWithRecords)
    .ForPage(1)
    .SendAsync(opts =>
    {
        opts.PageSize = pagingRequest.PageSize;
        opts.Format = DataFormat.Formatted;
        opts.FieldIds = new[] { 1, 2, 3 };
    });

Conclusion

By adding a fluent interface to our C# SDK, I think we can enhance its usability, improve code readability, and improve it's discoverability. These benefits will I think make our SDK more appealing to developers and lead to a better developer experience when working with it.