C# Design

INFO

For a comparison between Speakeasy's Go SDK and some of the popular open source generators, see this page

The C# SDKs are designed to be easy to use and easy to debug. Various decisions were made that guide the design of the SDK, these include:

• Minimal dependencies and relying on the C# standard library as much as possible.
• SDK & sub SDKs implement full interfaces so that the SDKs are ready for dependency-injection.
• Requests are async so that you can await them or run them asynchronously.
• Nullable fields for optional objects including fields/parameters/response and request bodies to ensure that the user can differentiate between a field not being set and a field being set to a zero value.
• Compatible with net5.0 projects for partial Unity support.

Examples

Authorization

Communicating authorization methods can be difficult, especially when there are multiple methods of authenticating or different styles of authorization for different endpoints. Swagger's Petstore OpenAPI schema (opens in a new tab) uses multiple types of authentication and different authentication schemes for different endpoints.

Here's an example of how to use an operation security configuration with a Speakeasy SDK:

var sdk = new PetstoreSDK();
 
var res = await sdk.Pet.FindPetsByStatusAsync(new FindPetsByStatusSecurity() {
    PetstoreAuth = "YOUR_ACCESS_TOKEN",
}, new FindPetsByStatusRequest() {
    Status = new List<FindPetsByStatusStatus>() {
        SDK.Models.FindPetsByStatusStatus.Sold,
        SDK.Models.FindPetsByStatusStatus.Pending,
        SDK.Models.FindPetsByStatusStatus.Sold,
    },
});

Importantly, the exact type of authentication required (FindPetsByStatusSecurity) is specified in the request.

Compare that to the code generated by Swagger CodeGen (opens in a new tab):

Configuration.Default.AccessToken = "YOUR_ACCESS_TOKEN";
 
var apiInstance = new PetApi();
var status = new List<string>(); 
 
try
{
    // Finds Pets by status
    List<Pet> result = apiInstance.FindPetsByStatus(status);
    Debug.WriteLine(result);
}
catch (Exception e)
{
    Debug.Print("Exception when calling PetApi.FindPetsByStatus: " + e.Message );
}

Note that there are two different methods of configuring security for the swagger petstore api, but which is required of each method is ambiguous, and the method of setting the api_key security is different from that of petstore_auth (above):

Configuration.Default.AddApiKey("api_key", "YOUR_API_KEY");

If you have any feedback or want to suggest improvements or ask for a new feature please get in contact in the #client-sdks channel in our public Slack (opens in a new tab).