Last updated: 2024-06-26

Using the API

Caution

Sample code provided in here is for demonstration and educational purposes only which provides customers with programming information regarding the products and is not intended for use in a production environment. All production code should always follow development best practices. All sample code here is supplied "AS IS" without any warranties or support.

In the previous step we saw how to get the Access Token using the ResourceOwner flow. Since we have the token it is now possible to start using the API. Depending on the access rights of the authenticated user we have different options.

In the introduction we talked about the Collection and Space segments of the API. When operating within a Space it is often required that we have the SAs-InformationFilter header set. In this section we will look at how we can get an Information Filter using the API.

In this example we have a Space identified as InControl. We can use the Space part of the API by using that Space id. The relative route will be /api/space/Incontrol.

C# Sample

Warning

A common mistake when using HttpClient is to use multiple instances of the HttpClient. You should reuse the same instance within an application.

We continue from the previous example by instantiating a new HttpClient. On this client we setup an Authorization Header using the token from the previous example.

We then make a GET request to https://essevm347.es.eurostep.com/api/space/InControl/informationfilter in order to get the default Information Filter for the current user within the InControl space.

httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token["access_token"].Value<string>());
httpClient.BaseAddress = new Uri("https://server.machine.net/api");

// Get information filter for space
var infoFilterResponse = await httpClient.GetAsync("https://server.machine.net/api/space/incontrol/informationFilter");
infoFilterResponse.EnsureSuccessStatusCode();

var resultJson = JObject.Parse(await infoFilterResponse.Content.ReadAsStringAsync());

Information Filter payload example:

{
  "href": "https://essevm347.es.eurostep.com/api/space/InControl/informationfilter",
  "data": {
    "owner": "eb43d157e3456d65ef00020000000000",
    "idContext": "eb43d157e4456d65e700020000000000",
    "effectivity": {
      "enabled": true,
      "role": "Actual",
      "mode": "Live"
    }
  }
}

Above we can see an example of the response to our GET request. Looking at the payload we can see that we have a JSON object with the two properties href and data. Nova is making use of HATEOAS REST architecture principles.

The href shows what resource that was requested and the data is the actual data response from the request. Depending on the type of data requested one might also get an array of links. These links depends on the current users access rights to the resource. More on this in the next section where we will look at requesting, creating, and editing SoftTypes.

Once we have the Information Filter we have the possibility to change the filter settings based on how we want to request data from Nova. This is done by simply editing the JSON object before setting it as the SAs-InformationFilter header.

Before the Information Filter can be set as the SAs-InformationFilter it must be converted to a URL Encoded Base64 string.

private static string Base64UrlEncode(byte[] input)
{
    var output = Convert.ToBase64String(input);
    output = output.Split('=')[0]; // Remove any trailing '='s
    output = output.Replace('+', '-'); // 62nd char of encoding
    output = output.Replace('/', '_'); // 63rd char of encoding
    return output;
}

var dataString = resultJson["data"].ToString();

var informationFilter = Base64UrlEncode(Encoding.UTF8.GetBytes(dataString));
httpClient.DefaultRequestHeaders.Add("SAs-InformationFilter", informationFilter);

Caching

When using the .Net HttpClient and you want to make use of the caching functionality in the Nova REST API use the following initialization of the HttpClient.

httpClient = new HttpClient(new WebRequestHandler()
{
  CachePolicy = new HttpRequestCachePolicy(HttpRequestCacheLevel.Default)
});

PowerShell Sample

Continuing from the previous example on the oAuth authorization/authentication. The following sample will show how to get the Information Filter and setting it to the SAs-InformationFilter header using PowerShell.

Download set-information-filter.ps1

$infoFilterUri = "https://essevm347.es.eurostep.com/api/space/InControl/informationfilter"

$bearerHeader = @{ "Authorization" = ("Bearer", $bearerToken -join " ") }

$response = Invoke-RestMethod -Uri $infoFilterUri -Headers $bearerHeader

$data = ConvertTo-Json $response.data

$data = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($data))
$data = $data.TrimEnd("=")
$data = $data.Replace("+", "-")
$data = $data.Replace("/", "_")

$bearerHeader = @{ 
    "Authorization" = ("Bearer", $bearerToken -join " ");
    "SAs-InformationFilter" = $data
}

Download sample

The code example provided in this document can be downloaded in a sample project.

Download Code

Table of Contents