AcceptRouterTompSdk 1.0.3

C# SDK for ACCEPT.ROUTER

A C# SDK to connect with the ACCEPT.ROUTER via the Transport Operator MaaS Provider (TOMP) API, version 1.3.0. This library provides C# classes and models based on the OpenAPI specification to facilitate integration with TOMP-compliant services.

Overview

The ACCEPT.ROUTER connects national and/or regional ticketing systems, making multi-modal and cross-border traveling possible. The router consists of a transaction functionality and a many-to-many functionality based upon the TOMP-API. For more details, see the Wiki-page. The TOMP API is an API between MaaS Providers and Transport Operators for planning and booking trips and corresponding assets. For more details on the TOMP-API visit the TOMP-WG GitHub repository. This SDK simplifies the connection with the ACCEPT.ROUTER and implementation of TOMP clients and servers in C# applications.

Onboarding

In order to start connecting to the MaaS-NL-Server send in an application to maasadministrator@acceptinstitute.eu with the following information:

Requirements

• .NET 8.0 or higher

Installation

Install the NuGet package into your project:

dotnet add package AcceptRouterTompSdk

Or, add the PackageReference to your .csproj file:

<ItemGroup>
    <PackageReference Include="AcceptRouterTompSdk" Version="1.0.3" />
</ItemGroup>

Dependencies

This project relies on the following key dependencies:

• Microsoft.Extensions.Http: For resilient HttpClient management.
• Microsoft.Extensions.Http.Polly: For advanced transient fault handling (retries, circuit breakers).
• Microsoft.Extensions.Hosting: For standard dependency injection and logging abstractions.
• Microsoft.Net.Http.Headers: For typed HTTP header management.

Note: JSON processing is handled via the built-in System.Text.Json library.

Outgoing requests

Usage

The main entry point for the SDK is the Tomp interface. You can create a TransportOperatorsApi instance using the builder pattern, which integrates directly with your IServiceCollection.

Example: Initialization and Ping

using System;
using System.Globalization;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;
using AcceptRouterTompSdk;
using AcceptRouterTompSdk.Model;
using AcceptRouterTompSdk.Exceptions;
using Microsoft.Extensions.DependencyInjection;

public class TompExample
{
    public static async Task Main(string[] args)
    {
        var services = new ServiceCollection();

        // Load your certificates
        var selfSignedCert = new X509Certificate2("my-client-cert.pfx", "password");
        var routerCert = new X509Certificate2("router-public-cert.cer");

        // Use the builder to register services
        Tomp.Builder()
            .TompUrl(new Uri("https://router.acceptinstitute.eu/"))
            .SelfSignedCertificate(selfSignedCert)
            .RouterCertificate(routerCert)
            .ApiDescription("TOMP-SDK")
            .ApiVersion(new SemVer(1, 3, 0))
            .AddLanguageTag(new CultureInfo("en-US"))
            .RegisterTransportOperatorApi(services, "your-maas-id");

        var serviceProvider = services.BuildServiceProvider();
        var api = serviceProvider.GetRequiredService<ITransportOperatorsApi>();

        try
        {
            await api.Ping("target-operator-id");
            Console.WriteLine("Successfully connected to the router.");
        }
        catch (MaliciousResponseException ex)
        {
            Console.WriteLine($"Security Validation Failed: {ex.Message}");
        }
        catch (TompException ex)
        {
            Console.WriteLine($"TOMP API Error: {ex.Message}");
        }
    }
}

The model classes are located in the AcceptRouterTompSdk.Model namespace. You can use these classes to construct requests and handle responses.

Incoming requests

Usage

This SDK can be used for the DTOs for incoming requests and outgoing responses. The model classes are located in the AcceptRouterTompSdk.Model namespace.

The SDK also provides middleware-classes for validating incoming signatures with the SignatureValidationMiddleware-class and signing responses with the ResponseSignatureMiddleware-class. For ease of use the extension methods WebApplicationBuilder.AddSignatureMiddlewareHelpers() and IApplicationBuilder.AddRouterMiddleware() are provided.

Example: Registering Middleware

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.AddSignatureMiddlewareHelpers();

        var app = builder.Build();
        
        app.UseWhen(
            httpContext => httpContext.Request.Path.StartsWithSegments("TOMP"),
            branch => branch.AddRouterMiddleware()
        );
    }
}

Documentation

The OpenAPI specification of TOMP 1.3.0 is available through Swagger.

Documentation of the ACCEPT.ROUTER is available on the ACCEPT. wiki

Access can be requested by mailing maasadministrator@acceptinstitute.eu

License

This project is licensed under the European Union Public Licence v. 1.2 (EUPL-1.2). See the LICENSE file for details.