README.md

Beam for C#

---

The Beam client for the .NET ecosystem provides a type-safe interface for consuming the Beam API. Please note that this client is meant to be used in server side applications, as following these instructions in a client-side environment would expose your API key to all users.

Connecting with Beam

In order to get started with Beam, you will need an API key. The API key for your game will be provided by your partner at Merit Circle.

Using the library in your project

You have to register necessary services in your dependency injection container, then all Api Clients can be used easily by injecting them into your classes.

Package reference

Simply include our Nuget from https://www.nuget.org/packages/Beam in your .csproj file like any other dependency:

<PackageReference Include="Beam" Version="1.0.*" />

Our deployment pipeline increments patch version on every deployment. You can either use a concrete version number or a wildcard(*) to always use newest SDK. We try to limit breaking changes but as this is still a new product, these might happen.

DI registration

In case of generic host applications:

using System;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Beam.Api;
using Beam.Client;
using Beam.Model;
using Beam.Extensions;

namespace YourProject
{
    public class Program
    {
        public static async Task Main(string[] args)
        {
            var host = CreateHostBuilder(args).Build();
            var api = host.Services.GetRequiredService<IAssetsApi>();
            GetAssetApiResponse apiResponse = await api.GetAssetAsync("todo");
            GetAssetResponse model = apiResponse.Ok();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args)
          .ConfigureApi((context, services, options) =>
          {
              // the type of token here depends on the api security specifications
              ApiKeyToken token = new("<your token>");
              options.AddTokens(token);

              // optionally choose the method the tokens will be provided with, default is RateLimitProvider
              options.UseProvider<RateLimitProvider<ApiKeyToken>, ApiKeyToken>();

              options.ConfigureJsonOptions((jsonOptions) =>
              {
                  // your custom converters if any
              });

              options.AddApiHttpClients(
                client: client => {
                  client.BaseAddress = new Uri("https://api.preview.onbeam.com/");
                },
                builder: builder => {
                  builder
                  .AddRetryPolicy(2)
                  .AddTimeoutPolicy(TimeSpan.FromSeconds(5))
                  .AddCircuitBreakerPolicy(10, TimeSpan.FromSeconds(30));
                  // add whatever middleware you prefer
                }
              );
          });
    }
}

or if you use new Web App templates:

using Beam.Client;
using Beam.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApi(options =>
{
    // the type of token here depends on the api security specifications
    var token = new ApiKeyToken("<your token>");
    options.AddTokens(token);

    // optionally choose the method the tokens will be provided with, default is RateLimitProvider
    options.UseProvider<RateLimitProvider<ApiKeyToken>, ApiKeyToken>();

    options.ConfigureJsonOptions((jsonOptions) =>
    {
        // your custom converters if any
    });

    options.AddApiHttpClients(
        client: client =>
        {
            client.BaseAddress = new Uri("https://api.preview.onbeam.com/");
        },
        builder: builder => {
            builder
            .AddRetryPolicy(2)
            .AddTimeoutPolicy(TimeSpan.FromSeconds(5))
            .AddCircuitBreakerPolicy(10, TimeSpan.FromSeconds(30));
            // add whatever middleware you prefer
        }
    );
});

// Add other services to the container.

var app = builder.Build();

(...)

app.Run();

Usage

To use Api clients provided by this SDK, simply inject them into your class:

public class MyService
{
    private readonly IGameApi _gameApi;

    public MyService(IGameApi gameApi)
    {
        _gameApi = gameApi;
    }

    public async Task GetMyGame()
    {
      var myGame = await _gameApi.GetGameAsync();
      (...)
    }
}

Questions

• What about HttpRequest failures and retries? You can configure Polly in the AddApiHttpClients((...), builder: (x) => ...) method.
• How are tokens used? Tokens are provided by a TokenProvider class. The default is RateLimitProvider which will perform client side rate limiting. Other providers can be used with the UseProvider method, you can implement your own if you don't want to get rate limited as well.
• Does an HttpRequest throw an error when the server response is not Ok? It depends how you made the request. If the return type is ApiResponse no error will be thrown, though the Content property will be null. StatusCode and ReasonPhrase will contain information about the error. If the return type is T, then it will throw. If the return type is TOrDefault, it will return null.
• How do I validate requests and process responses? Use the provided On and After methods in the Api class from the namespace Beam.Rest.DefaultApi. Or provide your own class by using the generic ConfigureApi method.
• How do I specify different ApiKeyToken for different ApiClients? You can now use exposed ApiKeyTokenProvider one each client to set custom ApiKey if needed. That token will only be used for that ApiClient instance.

    _gameApi.ApiKeyProvider.SetToken(new ApiKeyToken("<your token>"));

Documentation for Authorization

Authentication schemes defined for the API:

Beam API game key

• Type: API key
• API key parameter name: x-api-key
• Location: HTTP header

---

This C# SDK is automatically generated by the OpenAPI Generator project.