Exploring the OrderCloud .NET SDK

While I explore the capabilities of OrderCloud I am taking notes as to what I do and how different tools from OrderCloud work. In this blog post I will share some of the things I learned about the .NET version of the OrderCloud SDK.
The .NET SDK is available as a NuGet package by the name “OrderCloud.SDK” and works with all the latest .NET versions (I used .NET 6.0).

This SDK is a library you will probably always need to build any OrderCloud based application.
As we know, OrderCloud is a headless commerce platform, meaning that the only way of communicating with it is through APIs. The SDK makes it easier for you to perform API requests to OrderCloud by giving you a structured way of managing connections to OrderCloud and providing a typed approach for performing those requests.

The OrderCloudClient

The .NET version of the SDK uses ‘Clients’ to perform API requests and store access tokens.
The first thing you want to do is create one of those clients:

using OrderCloud.SDK;

var client = new OrderCloudClient(new OrderCloudClientConfig {
    ClientId = "my-client-id",
  
    // client credentials grant flow:
    ClientSecret = "my-client-secret"

    // OR password grant flow:
    Username = u,
    Password = p,

    Roles = new [] { ApiRole.OrderAdmin }
});

Each instance of a client automatically requests an access token on creation and stores it in its context. As you can see in above code snippet there are 2 ways of authenticating using these clients, using a username-password combination, or using a secret.
This can be used to create a client for each user which authenticates with your application, but if you don’t want to do that you can also use the impersonation approach, which is the approach I would choose when building browser-based applications.
With the impersonating approach you can create a single client using a ClientSecret for initial authentication. After that you can specify an access token which should be used for the API requests to OrderCloud. This access token you could get from your client-side application, so you would still need the JavaScript SDK or a direct API integration in your frontend application.

Once you have a client, you can use it to perform API requests.

var orders = await client.Orders.ListAsync(OrderDirection.Incoming, filters: new { Status = OrderStatus.Open });

As you can see in above example, the client provides a structure of methods and objects to perform API requests. This structure is based on the structure OrderCloud has put in their APIs, so for each category of APIs there is an instance of an interface in the OrderCloudClient object.

Each of these interfaces has an implementation for each API request part of that category. For structured objects like Products, Categories and Orders that includes CRUD like implementations.
So instead of having to build your own client and maintain HttpClients, you can use these OrderCloudClients to connect to the OrderCloud APIs in a much easier way.

Extended Properties

Another big advantage of using this SDK is that you can use Strongly Typed Extended Properties.
Extended Properties, or in short ‘xp’ (yes, very confusing coming from a Sitecore background), is a feature in OrderCloud which you can use to extend their data models. On many different models in OrderCloud you will see a property ‘xp’, for which you can specify any value to. This can be a simple flat object structure as well as multiple levels of objects.
These extended properties can be used on models like the Product and Category models.

There are two options in the .NET SDK on how you can specify this xp property.
The first option is to specify the dynamic object directly on the instance of the model. For example, on the OrderCloud.SDK.Product model we can specify the xp property as a dynamic object:

var product = new OrderCloud.SDK.Product();
product.xp = new {
    Brand = "Microsoft"
};

The second option is to set it using a strongly typed object. When you use the OrderCloud client to perform API requests to OrderCloud, you can in some cases also specify the Type of object the API request should send/return.
If you look at the interface for the Product APIs, then it has this Get method:

Task<TProduct> GetAsync<TProduct>(string productID, string accessToken = null) where TProduct : Product;

As you can see, you can specify a TProduct when calling this method. TProduct needs to be based on OrderCloud.SDK.Product. We can use OrderCloud.SDK.Productas Type for these requests. Txp in this case can be any type of object and is assigned to the ‘xp’ property of the Product:

// Type parameters:
//   Txp:
//     Specific type of the xp property. If not using a custom type, use the non-generic
//     Product class instead.
public class Product<Txp> : Product
{
    // Summary:
    //     Container for extended (custom) properties of the product.
    public new Txp xp
    {
        get        
        {
            return GetProp<Txp>("xp");
        }
        set
        {
            SetProp("xp", value);
        }
    }
}

So, for Txp we can create a new model which specifies the properties our extended properties object should have, for example:

public class ProductXp
{
    public string Brand { get; set; }
}

Now we can use these types to make the Get request to the OrderCloud APIs. The SDK will then deserialize the JSON response from OrderCloud and convert it to the type we specify.

var result = await client.Products.GetAsync<Product<ProductXp>>(productId);

This same principle is applied to the PartialProduct model:

public class PartialProduct<Txp> : PartialProduct

Verdict

I think the SDK is a very helpful library which really helps you understand and integrate with the APIs of OrderCloud.
There are still some things I can learn, for example about how authentication in OrderCloudClients works exactly and if I have been using them correctly thus far in my journey.
The structure of the OrderCloudClient is quite complex, just like the APIs themselves. This does, in my opinion, require you to build a shell around them instead of using the OrderCloudClient directly from your first layer of code. I would probably do that anyway to bring a certain level of abstraction in my application.

In a next blog post, I will demonstrate the use of another toolkit provided by OrderCloud, the OrderCloud Catalyst. Stay tuned!