ClockifyClient 1.2.8

Clockify Client

This project provides a strongly-typed C# client for interacting with the Clockify time tracking API. The client is automatically generated from Clockify's OpenAPI specification using Microsoft Kiota, ensuring type safety and up-to-date API coverage.

Prerequisites

• .NET Standard 2.0 / .NET 8.0 or later
• Clockify API key (Get your API key)

Installation

Get the ClockifyClient package from NuGet:

dotnet add package ClockifyClient

Usage

using ClockifyClient;

// Initialize the client with your API key
var client = ClockifyApiClientFactory.Create("your-api-key-here");

// Get user information
var user = await client.User.GetAsync();
Console.WriteLine($"Hello, {user.Name}!");

// Get workspaces
var workspaces = await client.Workspaces.GetAsync();
foreach (var workspace in workspaces)
{
    Console.WriteLine($"Workspace: {workspace.Name}");
}

// Get active times for the active workspace
var timeEntries = await client.V1.Workspaces[user.ActiveWorkspace].TimeEntries.Status.InProgress.GetAsync();

Error Handling

The client provides structured error handling:

try
{
    var user = await client.User.GetAsync();
}
catch (ApiException ex)
{
    Console.WriteLine($"API Error: {ex.ResponseStatusCode} - {ex.Message}");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Network Error: {ex.Message}");
}

Inspect Request & Response Bodies

Sometimes it's not enough to just know that the request failed, but you want to inspect the actual data sent or received.

var timeEntryRequest = new CreateTimeEntryRequest
{
    Description = "Important Work!",
    Start = DateTimeOffset.utcNow,
};

var inspectionOptions = new BodyInspectionHandlerOption
{
    InspectRequestBody = true,
    InspectResponseBody = true
};

try
{
    await _clockifyClient.V1.Workspaces[workspaceId].TimeEntries.PostAsync(timeEntryRequest, c => c.Options.Add(inspectionOptions));
}
catch (ApiException ex)
{
    Console.WriteLine($"API Error: {ex.ResponseStatusCode} - {ex.Message}");
    
    using var streamRequestReader = new StreamReader(inspectionOptions.RequestBody);
    Console.WriteLine(await streamRequestReader.ReadToEndAsync());
    
    using var streamResponseReader = new StreamReader(inspectionOptions.ResponseBody);
    Console.WriteLine(await streamResponseReader.ReadToEndAsync());
}

Development

Generating the Client

The client is generated using Microsoft Kiota. To regenerate the client:

# Install Kiota CLI
dotnet tool install --global Microsoft.OpenApi.Kiota

# Download the latest OpenAPI specification
curl -o clockify-openapi.json https://docs.clockify.me/openapi.json

# Apply modifications, see below

# Generate the client from OpenAPI spec
kiota generate --language CSharp --openapi clockify-openapi.json --class-name ClockifyApiClient --namespace-name ClockifyClient --output ClockifyClient --structured-mime-types application/json

Modifications

The OpenAPI specification provided by Clockify doesn't work out of the box with Kiota and requires some modifications.

Fix Cyclic Dependency

Remove a cyclic dependency, by deleting the self-reference from

"FeaturePlan": {
  "type": "object",
  "oneOf": [
    {
      "$ref": "#/components/schemas/FeaturePlan"
    }
  ],
  ...

to

"FeaturePlan": {
  "type": "object",
  ...

Fixing Enum Types

Replace the following part of the specification

"adminOnlyPages": {
  "type": "string",
  "description": "Represents a unique list of protected page enums.",
  "example": "[\"PROJECT\",\"TEAM\",\"REPORTS\"]",
  "enum": [
    "PROJECT",
    "TEAM",
    "REPORTS"
  ]
},

with this part instead

"adminOnlyPages": { 
    "type": "array", 
    "description": "Represents a unique list of protected page enums.", 
    "items": {
        "type": "string",
        "enum": ["PROJECT", "TEAM", "REPORTS"]
    },
    "example": "[\"PROJECT\", \"TEAM\", \"REPORTS\"]"
},

Remove the (outer) default property value for ImportTimeEntriesAndExpensesRequestV1.expenseFieldsForDetailedGroup.

Fixing Media Types

Replace occurrences of */* with application/json. Except for the file / export endpoints that use byte as format, namely:

• /v1/workspaces/{workspaceId}/expenses/{expenseId}/files/{fileId}
• /v1/workspaces/{workspaceId}/invoices/{invoiceId}/export

For example, like this:

"responses": { "200": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/TimeEntrySummaryReportDto" } } }, "description": "OK" } },

"responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeEntrySummaryReportDto" } } }, "description": "OK" } },

License

This project is licensed under the MIT License - see the LICENSE file for details.