Helsedir.Hint.Kodeverk.Client 3.0.9

HINT Felles Kodeverk

Inneholder modeller for Kodeverket og en klient for å bruke sammen med HttpClientFactory. Går mot v2 av HINT Kodeverk.

Klienten krever EntraId for å kunne hente kodeverk. Støtte for det kan settes opp med pakken Helsedir.Hint.Grunnmur.Klienter.EntraId / Hdir.Hint.Grunnmur.Klienter.EntraId hvis man ikke vil håndtere det selv.

Table of Contents

• Innledning
• Hdir.Hint.Kodeverk.Client
• Get started
• Get started: Advanced
• Caching

Innledning

Felles Kodeverk er et enkelt REST API for lagring og søk av både egendefinert samt kopier av eksterne kodeverk. Det består av 4 ressurstyper:

1. Kodeverk: Beskriver et kodeverk som identifiseres vha. en unik id (OID).
2. Element: Beskriver en kode som inngår i et bestemt kodeverk.
3. Relasjonsgruppe: Beskriver en relasjon mellom 2 kodeverk (kan være samme kodeverk) og fungerer som gruppering for elementrelasjoner.
4. Relasjon: Elementrelasjoner inngår i 1 relasjonsgruppe og beskriver relasjonen mellom 2 elementer. Elementene må tilhøre de respektive kodeverkene (fra/til) som relasjonsgruppen beskriver.

Hdir.Hint.Kodeverk.Client

Kodeverk.Client er en nuget pakke som er ment å gjøre det enklere og raskere å ta i bruk Felles Kodeverk Den inneholder C# klasser for serialisering\deserialisering til og fra json samt en hjelpe-klient som benytter HttpClient for å interaktere med Kodeverk APIet. Prosjektet targeter .NET standard 2.0 og har kun avhengighet til Microsoft.AspNet.WebApi.Client.

For brukere som trenger å tilpasse oppførsel til HTTP Request\Response til klienten kan dette gjøres vha. DelegatingHandler slik som f.eks en egenlaget CorrelationIdDelegatingHandler. Hvis det er ønskelig å endre oppførselen til selve klienten så er alle metodene virtual og kan overskrives ved å arve fra KodeverkClient, se eksempel på caching.

Get started

Klienten er ment å brukes sammen med HttpClientFactory og Dependency-Injection (men dette er ikke nødvendig). Kodeverk-APIet støtter både filtrering, sortering, paginering og oversetting, men for de fleste forsystemer vil behovet kun være å hente alle koder som inngår i et spesifisert kodeverk, påfølgende kode er et eksempel på dette.

using Hdir.Hint.Kodeverk;
...

// Registrerer klienten i Dependency-Injection. 
public static void AddKodeverkClient(IServiceCollection services)
{
    services
        .AddHttpClient<IKodeverkClient, KodeverkClient>()
        .ConfigureHttpClient(client =>
        {
            client.BaseAddress = new Uri("https://hint-api-st.test.helsedir.no/intern/kodeverk/apimv2");
            // APIM subscription key
            client.DefaultRequestHeaders.Add(HttpClientConstants.HeaderApimSubscriptionKey, options.ApimSubscriptionKey);
        })
        // Autentisering/Autorisering vha HelseId.
        .AddHttpMessageHandler<TokenSetterDelegatingHandler>();
        // EntraId-handler fra pakken Hdir.Hint.Grunnmur.Klienter.EntraId:
        // .AddHttpMessageHandler<EntraIdHandler>();
}

public class ExampleClass
{
    private readonly IKodeverkClient _client;

    public ExampleClass(IKodeverkClient client)
    {
        _client = client;
    }

    // Eksempel der vi kun er interessert i å hente alle kodene i et kodeverk.
    public async Task<string[]> GetCodesAsync(string kodeverkId)
    {
        var elements = await _client.AllElementsAsync(kodeverkId);
        var codes = elements.Select(x => x.Kode).ToArray();

        return codes;
    }
}

Get started: Advanced

Følgende er et mer komplekst eksempel der endepunktet til HINT hentes fra konfigurasjon og det benyttes en DelegationHandler som beriker HTTP-requestene med en x-Correlation-ID header. CorrelationIdDelegatingHandler er her bare brukt som et eksempel og finnes ikke i Nugeten, den må implementeres av brukerene selv dersom de ønsker den funksjonaliteten.

public static void AddKodeverkClient(this IServiceCollection services)
{
    services
        .AddOptions<MyConfig>()
        .Configure<IConfiguration>((ops, config) => config.Bind("Integrations:Hint", ops));

    services
        .AddHttpClient<IKodeverkClient, KodeverkClient>()
        .ConfigureHttpClient((sp, client) =>
        {
            var options = sp.GetRequiredService<IOptions<MyConfig>>().Value;
            client.BaseAddress = new Uri($"{options.Endpoint}");
            // APIM subscription key
            client.DefaultRequestHeaders.Add(HttpClientConstants.HeaderApimSubscriptionKey, options.ApimSubscriptionKey);   
        })
        // Autentisering/Autorisering vha EntraId.
        .AddHttpMessageHandler<TokenSetterDelegatingHandler>()
        .AddHttpMessageHandler<CorrelationIdDelegatingHandler>()
        .AddHttpMessageHandler<LoggingDelegatingHandler>()
        // .AddHttpMessageHandler<EntraIdHandler>() // EntraId-handler fra pakken Hdir.Hint.Grunnmur.Klienter.EntraId
        .AddTransientHttpErrorPolicy(x => x.WaitAndRetryAsync(new[] { TimeSpan.FromSeconds(1) })); 
}

Caching

Et kodeverk endrer seg sjelden og tåler å ha en forsinkelse før eventuelle endringer reflekteres, derfor er dette en god kandidat for aggressiv caching. Kodeverk.Client Nuget pakken inneholder ikke en ferdig cache-implementasjon siden behovene til forsystemer vil være forskjellige.

Følgende er et eksempel på hvordan et forsystem kan utvide KodeverkClient til å bruke Microsoft sin MemoryCache. Merk at ElementApiQuery i dette eksempelet blir brukt som Cache-Key; det fungerer fordi ElementApiQuery implementerer IEquatable. Alle klassene i Nuget pakken implementerer IEquatable + noen egenlagde grensensitt: IDeepComparable og IDeepCopyable.

public class CachedKodeverkHttpClient : KodeverkClient
{
    private readonly IMemoryCache _cache;

    public CachedKodeverkHttpClient(
        HttpClient httpClient,
        IMemoryCache cache)
        : base(httpClient)
    {
        _cache = cache;
    }

    public override Task<PagedApiModel<ElementApiModel>> SearchElementsAsync(
        ElementApiQuery query = null,
        CancellationToken ct = default(CancellationToken))
        => _cache.GetOrCreateAsync(query, entry =>
        {
            entry.SetAbsoluteExpiration(TimeSpan.FromDays(1));
            return base.SearchElementsAsync(query, ct);
        });
}

...

// Registrerer og brukes på vanlig måte.
public static void AddKodeverkClient(IServiceCollection services)
{
    services
        .AddHttpClient<IKodeverkClient, CachedKodeverkHttpClient>()
    ...
}