How to use OData to get a list of orders?

This example of using the Jasmin Web API illustrates how you can use the API to retrieve the list of orders available in the system, using an OData filter.

This sample code was developed in a C# console application and is available on a code example repository.

This example uses the request to the WebAPI Jasmin. For ROSE, it might be necessary to adjust entity properties.

AccountKey and SubscriptionKey

First, these two data are required by the Web API and must be defined in the code. To do this, we use two constants that will be used in the request URLs.

private const string AccountKey = "XXXXX"; // TODO: put your account key here
private const string SubscriptionKey = "XXXXX-XXXX"; // TODO: put your account key here

Access token

To access the Web API you also need the authorization token associated with the user and the Jasmin subscription. In the example we use a constant again to store this value.

private const string AccessToken = "XXXX"; // TODO: put the authorization access token here (this should be obtained previously)

HttpClient

Para fazer chamadas a uma Web API REST em C# pode utilizar-se a classe System.Net.Http.HttpClient.

using (HttpClient client = new HttpClient())
{
    (…)
}

Access token configuration

Web API requests always require the previous access token. This must be included in the request headers.

client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", AccessToken);

Order data

For the order query endpoint using OData filters, order data will be returned in the response message body in JSON format.

To do this, we created a very simple C# class that only includes the order attributes that are required for the example.

internal class OrderResource
{
    #region Internal Properties
  
    public Guid Id
    {
        get;
        set;
    }
    public string DocumentType
    {
        get;
        set;
    }
    public string Serie
    {
        get;
        set;
    }
    public int SeriesNumber
    {
        get;
        set;
    }
    public string Company
    {
        get;
        set;
    }

    #endregion
}

Running the request

The Web API call can now be run using the correct endpoint. Note that the verb used is GET and the response is returned in an IDisposable HttpResponseMessage type.

// URI of the endpoint

string endpoint = string.Format(CultureInfo.CurrentCulture, "{0}/{1}/{2}/sales/orders", ApiBaseAddress, AccountKey, SubscriptionKey);

// Send the request (GET)

Uri endpointUri = new Uri(endpoint);
using (HttpResponseMessage response = await client.PostAsync(endpointUri, content))
{
    (…)
}

Response handling

The endpoint can return two types of responses: success or error. In case of success, the body will include the list of orders, according to the OData filters applied. In the event of an error, the result will include an error message that depends on the error.

// Failed?

if (!response.IsSuccessStatusCode)
{
    string errorContent = await response.Content.ReadAsStringAsync();
    StringBuilder sb = new StringBuilder();
    sb.AppendLine(string.Format(CultureInfo.CurrentCulture, "The requested failed with status code {0} ({1}).", (int)response.StatusCode, response.StatusCode));
    if (!string.IsNullOrWhiteSpace(errorContent))
    {
        sb.Append(string.Format(CultureInfo.CurrentCulture, "Message: {0}.", errorContent));
    }

    throw new InvalidOperationException(sb.ToString());
}

// Succeeded

string json = await response.Content.ReadAsStringAsync();
JsonSerializerSettings settings = new JsonSerializerSettings()
{
  ContractResolver = new CamelCasePropertyNamesContractResolver(),
  Formatting = Formatting.Indented
};

PageResult orders = JsonConvert.DeserializeObject(json);
Console.WriteLine("The orders attributs were obtained with success.");
foreach (OrderResource order in orders)
{
  Console.WriteLine("Order: {0}.{1}.{2}", order.DocumentType, order.Company, order.SeriesNumber);
}

Console.WriteLine("Count: {0}", orders.Count);

Retrieving the desired attributes from the list of orders using OData filters in the Web API is this simple.