Client Code Generation

Writing the code to make HTTP requests manually may be tedious and repetitive. Developers may instead opt to generate the required code for them, using our provided OpenAPI Specification file.

The specification is available either from the API Reference page: Open API Reference or from any hosted WebTSM Service under

CODE

GET /docs/specification.json

or

CODE

GET /docs/specification.yaml

The tools required to generate code from this file may vary depending on the desired output language. The following example shows how to generate C# code.

Generating the Client using NSwagStudio

Download and install NSwagStudio: https://github.com/RicoSuter/NSwag/wiki/NSwagStudio
Start NSwagStudio, go to the "File" menu, select "Open" and choose the pre-configured settings file: nswag.json
Insert the URL of the WebTSM Services specification file (e.g. https://api.example.com/docs/specification.json) or insert the yaml/json specification file manually
On the right side, click on the "CSharp Client" tab and change the namespace as you like
Click on the "Output" tab and then below on the "Generate Outputs" button
The generated output can now be copied to an empty C# file
And that's all!!

Examples of Use

Once you successfully created the C# client, refer to the following simple code snippets to get you started.

Please note that you must enter the correct URL of the WebTSM Services in line 27 as well as user name and password in lines 29 and 30 respectively

This example uses the Basic authentication scheme. In order to authenticate using a pre-obtained access token, please alter the lines 29-32 to set the header accordingly

C#

var access_token = "ey....<set your access token (base-64 encoded JWT) here>"
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", access_token);

The steps required for obtaining a token may vary depending on the identity provider used and cannot be covered in this section. Please refer to the appropriate documentation of the identity provider.

C#

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace MyNamespace
{
	class Program
	{
		static void Main(string[] args)
		{
			Console.WriteLine("Hello World!");

			Task task = AutoGeneratedClientExamples();
			task.Wait();
		}

		const string repository = "ZAMS";

		private static async Task AutoGeneratedClientExamples()
		{
			// Create HTTP client
			using HttpClient httpClient = new HttpClient();
			httpClient.BaseAddress = new Uri("https://api.example.com/");

			var username = "yourusername";
			var password = "yourpassword";
			var credentials = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{username}:{password}"));
			httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

			// Create WebTSM Services client
			Client client = new Client(httpClient);

			var interval = new Interval() { Value = 2, Multiplier = 15 }; // 15 minutes
			var unit = "KW";

			int timeSeriesID = await CreateTimeSeries(client, interval, unit);

			await SearchTimeSeries(client);

			await GetTimeSeries(client, timeSeriesID);

			await SaveData(client, timeSeriesID, interval, unit);

			await GetData(client, timeSeriesID);

			int attributeID = await CreateAttribute(client);

			await AssignAttributeToTimeSeries(client, timeSeriesID, attributeID);

			await GetAssignedAttributes(client, timeSeriesID);

			// Cleanup
			await client.DeleteTimeSeriesByIDAsync(timeSeriesID, repository);
			await client.DeleteAttributeByIDAsync(attributeID, repository);
		}

		private async static Task<int> CreateTimeSeries(Client client, Interval interval, string unit)
		{
			TimeSeries timeSeries = new TimeSeries();
			timeSeries.Name = "MyTimeSeries";
			timeSeries.Type = 1; // Begin (left-aligned) time series
			timeSeries.Interval = interval;
			timeSeries.Unit = unit;

			int timeSeriesID = await client.PostTimeSeriesAsync(timeSeries, repository);
			Console.WriteLine($"Time series created. ID: {timeSeriesID}.");

			return timeSeriesID;
		}

		private static async Task SearchTimeSeries(Client client)
		{
			var result = await client.GetTimeSeriesAsync(repository);
			Console.WriteLine($"All time series count: {result.Count}");

			result = await client.GetTimeSeriesAsync(repository, name: "MyTimeS%");
			Console.WriteLine($"Time series found: {result.First().Name}");
		}

		private static async Task GetTimeSeries(Client client, int timeSeriesID)
		{
			var timeSeries = await client.GetTimeSeriesByIDAsync(timeSeriesID, repository);
			Console.WriteLine($"Time seried retrieved: {timeSeries.Name}");
		}

		private static async Task SaveData(Client client, int timeSeriesID, Interval interval, string unit)
		{
			var dataItems = new TimeSeriesDataItem[96];
			for(int i = 0; i < 96; i++)
			{
				dataItems[i] = new TimeSeriesDataItem()
				{
					From = DateTimeOffset.Now.Date.AddMinutes(i * 15),
					Value = i + 1
				};
			}

			var data = new TimeSeriesData()
			{
				Interval = interval,
				Unit = unit,
				Data = dataItems
			};

			await client.PostTimeSeriesDataByIDAsync(data, timeSeriesID, repository);

			Console.WriteLine("Time series data created.");
		}

		private static async Task GetData(Client client, int timeSeriesID)
		{
			var retrievedData = await client.GetTimeSeriesDataByIDAsync(DateTimeOffset.Now.Date, DateTimeOffset.Now.Date.AddDays(1), timeSeriesID, repository);

			Console.Write("Retrieved data: ");
			foreach(var item in retrievedData.Data)
				Console.Write($" {item.Value}");

			Console.WriteLine();
		}

		private static async Task<int> CreateAttribute(Client client)
		{
			var attribute = new Attribute()
			{
				Name = "MyAttribute",
				Type = 2 // Text
			};

			int attributeID = await client.PostAttributeAsync(attribute, repository);
			Console.WriteLine($"Attribute created. ID: {attributeID}");

			return attributeID;
		}

		private static async Task AssignAttributeToTimeSeries(Client client, int timeSeriesID, int attributeID)
		{
			var attributeValues = new Dictionary<string, string>()  {
				{ DateTimeOffset.Now.Date.ToString("o"), "MyAssignedAttributeValue" }
			};

			await client.PostTimeSeriesAttributeValuesByIDAsync(attributeID, timeSeriesID, repository, attributeValues);

			Console.WriteLine("Attribute assigned to time series.");
		}

		private static async Task GetAssignedAttributes(Client client, int timeSeriesID)
		{
			var assignedAttributes = await client.GetTimeSeriesAttributesByIDAsync(timeSeriesID, repository);
			Console.WriteLine($"All assigned attributes count: {assignedAttributes.Count}");

			Console.WriteLine($"Assigned attribute - ID: {assignedAttributes.First().AttributeID}, Value: {assignedAttributes.First().Values.First().Value}");
		}
	}
}

Restrictions

Currently popular client generators support only the default mediatype format for each endpoint.

In case a different format is required it is necessary to manually extend the generated client.

Example

CODE

/repositories/{repository}/timeseries/{ID}/data

For this endpoint the generated client will create an endpoint with the mediatype format "timestamp" as this is the default mediatype format.

In order to to read out data from this endpoint with the format "timespan" a manual implementation is necessary.