Guido van Tricht

Sitecore OrderCloud - Which SDK should I use?

Over the past few weeks I have been playing around with Sitecore OrderCloud. I learned that there are multiple ways on how you can build an application around the OrderCloud APIs.

If you want to start building your own application using OrderCloud but don’t have an account yet, you can create a free sandbox account. A good place to start is by following the Getting Started tutorial on ordercloud.io: https://ordercloud.io/learn/getting-started/welcome-to-ordercloud

OrderCloud comes with a couple of different SDKs which you can use to base your application on. In this post I will be taking a look at the following:

  • Open API
  • JavaScript SDK
  • .NET SDK

Open API

You can build your application by directly using OrderCloud’s APIs.
Their APIs have been built based on the Open API standard. The specs can be found here: https://api.ordercloud.io/v1/openapi/v3
These specs can be imported in Postman to make it easier for you to interpret the APIs and to test them out.

The APIs however are quite complex in my opinion, so I would not use them to directly integrate with in my application.
The Postman collections do however give you a good understanding of what is possible in OrderCloud, so it is still great to have them while you are developing your application.

One API you could use directly is the /oauth/token request to log a user in. This API will provide you with a token which you then need to use as a Bearer token to authenticate with the other APIs.

JavaScript SDK

OrderCloud provides a JavaScript SDK which can be used to build a typed integration in any client-side framework. The SDK has been built with TypeScript support, so you can also use it in TypeScript based frameworks.

The SDK can easily be installed using NPM:

npm install ordercloud-javascript-sdk --save

The first thing you want to build for your application is a login form. When submitting this form you want to authenticate against OrderCloud’s APIs. Doing this using the JS SDK is quite simple as you can do it using typed objects:

import { Auth, Tokens } from 'ordercloud-javascript-sdk';

const username = 'YOUR_USERNAME'; //username of the user logging in
const password = 'YOUR_PASSWORD'; //password of the user logging in
const clientID = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'; //clientID of the application the user is logging in to (\[sign up for free](https://portal.ordercloud.io/register)
const scope = \['FullAccess']; //string array of \[roles](https://ordercloud.io/knowledge-base/security-profiles) the application has access to

Auth.Login(username, password, clientID, scope)
  .then(response => {
      //store token, now any subsequent calls will automatically set this token in the headers for you
      const token = response.access_token;
      Tokens.SetAccessToken(token)
  })
  .catch(err => console.log(err));

The Auth.Login method will return an access token. This token should be uses in any subsequent API calls to OrderCloud as it authenticates the user when performing the next request.
As you can see in above example, this token is stored in the application context using Tokens.SetAccessToken. After doing this any next requests will automatically use the stored token.

We can use any of OrderCloud’s APIs in the same way as above Login functionality using type objects, like getting a list of products:

import { Me } from 'ordercloud-javascript-sdk';

// Get products
Me.ListProducts()
  .then(productList => console.log(productList))

The full JavaScript SDK is available on GitHub and describes the many different options it offers: https://github.com/ordercloud-api/ordercloud-javascript-sdk

.NET SDK

Very similar to the JavaScript SDK, OrderCloud also has a .NET C# based version of their SDK.
The 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).

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 it’s 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 });

Above example shows how you could get a list of orders from OrderCloud. The retrieved list will be based on the context user as defined in the client instance.
If you want to impersonate a user, you can specify the access token in the same method:

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

This SDK is also available on GitHub: https://github.com/ordercloud-api/ordercloud-dotnet-sdk

Which approach should I choose?

Each of these SDKs are valid options to build your application on, it really depends on the application you want to build, their purpose and your own opinion.

In would probably always choose the .NET SDK as a basis for my application, simply because of all the possibilities .NET offers me.
For the client-side application I might use the JavaScript SDK, but the only purpose of integrating with OrderCloud in my client-side is to authenticate a user and retrieve an access token. Using the full JavaScript SDK for only this purpose might be a bit overkill, so it might be easier to create a simple integration with the authentication API directly.