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.

It is of utmost importance that the fetched access token is cached by the client for the duration of its validity and reused for subsequent requests. The Switch Authorization Server will soon start imposing rate limits on the token endpoint which when reached will reject the requests to fetch an access token for a given time period.

Please note that the samples provided below do not do any caching of the access token, they are as stated, just a sample that should not be used in production environments.

Samples

C#

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 Audience = "<audience>";
        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 },
                { "audience", Audience }
            }));
            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.
        }
    }
}

NodeJS

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