MarkZither.KimaiDotNet.ApiClient

KimaiDotNet

A .NET client library for the Kimai time-tracking REST API.

Overview

MarkZither.KimaiDotNet.ApiClient is a strongly-typed C# client for the Kimai API, generated from the Kimai OpenAPI 3.0 specification using Microsoft Kiota. It targets netstandard2.0 and works with .NET 6+, .NET Framework 4.6.2+, and any platform that supports .NET Standard 2.0.

Breaking change in v1.0.0-beta1: The client was re-generated with Microsoft Kiota (replacing AutoRest). The API surface has changed significantly. See the migration guide below.

Installation

dotnet add package MarkZither.KimaiDotNet.ApiClient

Quick Start

Kimai uses token-based authentication. Pass your username and API token via custom HTTP headers.

using MarkZither.KimaiDotNet;
using Microsoft.Kiota.Abstractions.Authentication;
using Microsoft.Kiota.Http.HttpClientLibrary;
using System.Net.Http;

// Configure the HttpClient with auth headers
var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Add("X-AUTH-USER", "your-username");
httpClient.DefaultRequestHeaders.Add("X-AUTH-TOKEN", "your-api-token");

// Build the Kiota adapter and client
var adapter = new HttpClientRequestAdapter(new AnonymousAuthenticationProvider(), httpClient: httpClient);
adapter.BaseUrl = "https://your-kimai-server.example.com";

var client = new KimaiClient(adapter);

// Get server version
var version = await client.Api.Version.GetAsync();
Console.WriteLine($"Kimai version: {version?.Version}");

// List activities
var activities = await client.Api.Activities.GetAsync();
foreach (var activity in activities ?? [])
{
    Console.WriteLine($"  {activity.Id}: {activity.Name}");
}

// Get the current user
var me = await client.Api.Users.Me.GetAsync();
Console.WriteLine($"Logged in as: {me?.Username}");

Authentication

Kimai supports two header-based auth schemes:

Available Endpoints

The client exposes all Kimai API routes via a fluent builder pattern under client.Api.*:

Creating Resources

Kiota models use object-initializer syntax:

using MarkZither.KimaiDotNet.Models;

var newActivity = new ActivityEditForm
{
    Name = "My Activity",
    Comment = "Optional description",
    Visible = true
};

var created = await client.Api.Activities.PostAsync(newActivity);
Console.WriteLine($"Created activity id: {created?.Id}");

Error Handling

Kiota throws Microsoft.Kiota.Abstractions.ApiException on non-2xx responses:

using Microsoft.Kiota.Abstractions;

try
{
    var activity = await client.Api.Activities["123"].GetAsync();
}
catch (ApiException ex)
{
    Console.WriteLine($"API error {ex.ResponseStatusCode}: {ex.Message}");
}

Migrating from v0.4.x

v1.0.0-beta1 replaces the AutoRest-generated client with a Kiota-generated one. Key differences:

Versioning

Releases follow Semantic Versioning. NuGet packages are published automatically when a v* tag is pushed to the repository.

To publish a new release:

git tag v1.0.0-beta1
git push origin v1.0.0-beta1

Regenerating the Client

The client is generated from docs/document.json (the Kimai OpenAPI 3.0 spec) using Microsoft Kiota.

Install the Kiota tool:

dotnet tool install --global Microsoft.OpenApi.Kiota

Regenerate from the repo root:

kiota generate \
  --language CSharp \
  --class-name KimaiClient \
  --namespace-name MarkZither.KimaiDotNet \
  --openapi docs/document.json \
  --output src/KimaiDotNet.Core \
  --exclude-backward-compatible \
  --clean-output

After regenerating, update the descriptionLocation in src/KimaiDotNet.Core/kiota-lock.json if the path to document.json has changed.

Building from Source

dotnet restore
dotnet build -c Release
dotnet test

License

MIT