Code samples

Learn how to communicate with the Switch OpenADR 3 VTN API through simple code samples.

Overview

Using the Switch OpenADR 3 VTN API is as simple as communicating with any REST API. Below you will find examples of how to authenticate with the VTN prior to making any request to it and it follows with example of how to make a simple request.

Information about the VTN URL you can find on the VTN Endpoint page, details about the authentication parameters at Token Endpoint, and information about the available API endpoints at API Reference page.

Samples shown below are not meant to be production-ready code or to be used as-is. They are meant to illustrate the use of an API or feature in the simplest way possible. For this reason, these samples make certain assumptions on hosting, authentication, request/response handling etc.

Samples

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

namespace ConsoleAppOadr3SamplesDocs
{
    internal class Application
    {
        private const string TokenProviderUrl = "<token_provider_url>";
        private const string ClientId = "<your_client_id>";
        private const string ClientSecret = "<your_client_secret>";
        private const string GrantType = "client_credentials";
        private const string Scope = "<scope>";
        private const string VtnUrl = "<vtn_url>";

        static async Task Main()
        {
            // NOTE: This is just a very simple example for authenticating.
            // Ideally you would use an established library instead, allowing token re-use
            // and refresh token when needed.
            var accessToken = await GetAccessToken();
            // NOTE: Another way to get access token is to call the Auth endpoint of the VTN but
            // this way is to be used for testing purposes only.
            
            // Search for available programs.
            using var client = new HttpClient();
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
            var response = await client.GetAsync($"{VtnUrl}/programs");
            var content = await response.Content.ReadAsStringAsync();
            var programs = JsonSerializer.Deserialize<Program[]>(content);
            var program = programs.FirstOrDefault();
            
            // Search for available events with filters.
            response = await client.GetAsync($"{VtnUrl}/events?programID={program.Id}&skip=1&limit=5");
            content = await response.Content.ReadAsStringAsync();
            var events = JsonSerializer.Deserialize<Event[]>(content);

            // Create subscription.
            var subscription = new Subscription
            {
                ProgramId = program.Id,
                ClientName = "MyVEN",
                ObjectOperations = new List<SubscriptionObjectOperation>
                {
                    new()
                    {
                        Objects = new List<string> { "EVENT", "REPORT" },
                        Operations = new List<string> { "POST", "PUT", "DELETE" },
                        CallbackUrl = "https://mycompany.com/callback"
                    }
                }
            };
            var payload = new StringContent(JsonSerializer.Serialize(subscription), Encoding.UTF8, "application/json");
            client.DefaultRequestHeaders.Accept.Clear();
            client.DefaultRequestHeaders.Add("Accept", "application/json");
            await client.PostAsync($"{VtnUrl}/subscriptions", payload);
        }

        private static async Task<string> GetAccessToken()
        {
            using var client = new HttpClient();
            var response = await client.PostAsync(TokenProviderUrl, new FormUrlEncodedContent(new Dictionary<string, string>
            {
                { "grant_type", GrantType },
                { "client_id", ClientId },
                { "client_secret", ClientSecret },
                { "scope", Scope }
            }));
            var content = await response.Content.ReadAsStringAsync();
            var token = JsonSerializer.Deserialize<Token>(content);
            return token.AccessToken;
        }

        private class Token
        {
            [JsonPropertyName("access_token")]
            public string AccessToken { get; init; }
        }

        private class Program
        {
            [JsonPropertyName("id")]
            public string Id { get; set; }
            
            [JsonPropertyName("programName")]
            public string ProgramName { get; set; }

            // Remaining fields omitted for this example, see the API reference documentation for the full list.
        }

        private class Event
        {
            [JsonPropertyName("id")]
            public string Id { get; set; }
            
            [JsonPropertyName("programID")]
            public string ProgramId { get; set; }
            
            [JsonPropertyName("eventName")]
            public string EventName { get; set; }

            // Remaining fields omitted for this example, see the API reference documentation for the full list.
        }

        private class Subscription
        {
            [JsonPropertyName("clientName")]
            public string ClientName { get; set; }
            
            [JsonPropertyName("programID")]
            public string ProgramId { get; set; }
            
            [JsonPropertyName("objectOperations")]
            public List<SubscriptionObjectOperation> ObjectOperations { get; set; }

            // Remaining fields omitted for this example, see the API reference documentation for the full list.
        }

        private class SubscriptionObjectOperation
        {
            [JsonPropertyName("objects")]
            public List<string> Objects { get; set; }
            
            [JsonPropertyName("operations")]
            public List<string> Operations { get; set; }
            
            [JsonPropertyName("callbackUrl")]
            public string CallbackUrl { get; set; }

            // Remaining fields omitted for this example, see the API reference documentation for the full list.
        }
    }
}

The Switch platform has an official client library for .NET which you can find here.

PreviousPayloadsNextLibraries

Last updated

Was this helpful?