Jolpica.F1 0.1.0

Jolpica.F1

A production-quality, strongly-typed .NET API client library for the Jolpica F1 API.

Features

• ✅ 100% Endpoint Coverage - All endpoints from the OpenAPI spec are available
• ✅ Strongly Typed - Full DTO support with nullable reference types
• ✅ Dependency Injection Ready - Easy integration with IServiceCollection
• ✅ HttpClientFactory Support - Proper use of typed HttpClient
• ✅ Optional Authentication - Works with or without API tokens
• ✅ Cancellation Token Support - All methods support cancellation
• ✅ Comprehensive Error Handling - Custom exceptions with detailed error information
• ✅ System.Text.Json - Modern JSON serialization (no Newtonsoft dependency)

Installation

dotnet add package Jolpica.F1

Or via Package Manager:

Install-Package Jolpica.F1

Quick Start

1. Register the Client

In your Program.cs or Startup.cs:

using Jolpica.F1;

var builder = WebApplication.CreateBuilder(args);

// Register the Jolpica F1 client
builder.Services.AddJolpicaF1Client(options =>
{
    // API token is optional - many endpoints are public
    options.ApiToken = builder.Configuration["Jolpica:ApiToken"];
    options.BaseUrl = "https://api.jolpi.ca"; // Default
    options.Timeout = TimeSpan.FromSeconds(30); // Default
});

var app = builder.Build();

2. Use the Client

using Jolpica.F1;

public class MyService
{
    private readonly IJolpicaF1Client _client;

    public MyService(IJolpicaF1Client client)
    {
        _client = client;
    }

    public async Task GetCircuitsAsync(CancellationToken cancellationToken = default)
    {
        // Get first page of circuits
        var circuits = await _client.GetCircuitsAsync(page: 1, cancellationToken: cancellationToken);
        
        Console.WriteLine($"Total circuits: {circuits.Metadata.Count}");
        foreach (var circuit in circuits.Data)
        {
            Console.WriteLine($"{circuit.Name} - {circuit.Country}");
        }
    }

    public async Task GetDriverAsync(string driverId, CancellationToken cancellationToken = default)
    {
        var driver = await _client.GetDriverAsync(driverId, cancellationToken);
        Console.WriteLine($"{driver.Data.FirstName} {driver.Data.LastName}");
    }
}

Authentication

The Jolpica F1 API uses token-based authentication via the Authorization header with the format Token {token}.

Important: Many endpoints are public and do not require authentication. If you don't provide an API token, the client will work fine for public endpoints.

With API Token

builder.Services.AddJolpicaF1Client(options =>
{
    options.ApiToken = "your-api-token-here";
});

Without API Token (Public Endpoints Only)

builder.Services.AddJolpicaF1Client(); // No token needed for public endpoints

Available Endpoints

The client provides strongly-typed methods for all endpoints:

Data Dumps

• GetDumpsOverviewAsync() - Get overview of available database dumps
• DownloadDelayedDumpAsync(dumpType?) - Download delayed dump (14+ days old)
• DownloadLatestDumpAsync(dumpType?) - Download latest dump (requires auth)

Circuits

• GetCircuitsAsync(countryCode?, page?, year?) - List all circuits
• GetCircuitAsync(apiId) - Get circuit details

Drivers

• GetDriversAsync(countryCode?, page?, role?, teamId?, year?) - List all drivers
• GetDriverAsync(apiId) - Get driver details

Laps

• GetLapsAsync(...) - List all laps with filtering
• GetLapAsync(apiId) - Get lap details

Pit Stops

• GetPitStopsAsync(...) - List all pit stops with filtering
• GetPitStopAsync(apiId) - Get pit stop details

Rounds

• GetRoundsAsync(...) - List all rounds with filtering
• GetRoundAsync(apiId) - Get round details

Session Entries

• GetSessionEntriesAsync(...) - List all session entries with filtering
• GetSessionEntryAsync(apiId) - Get session entry details

Sessions

• GetSessionsAsync(...) - List all sessions with filtering
• GetSessionAsync(apiId) - Get session details

Teams

• GetTeamsAsync(countryCode?, page?, year?) - List all teams
• GetTeamAsync(apiId) - Get team details

Schedules

• GetSchedulesAsync(page?) - List all season schedules
• GetScheduleAsync(year) - Get detailed schedule for a season

Error Handling

The client throws JolpicaApiException for non-success HTTP responses:

try
{
    var circuit = await _client.GetCircuitAsync("circuit-id");
}
catch (JolpicaApiException ex)
{
    Console.WriteLine($"API Error: {ex.Message}");
    Console.WriteLine($"Status Code: {ex.StatusCode}");
    Console.WriteLine($"Request URL: {ex.RequestUrl}");
    Console.WriteLine($"Response: {ex.ResponseBody}");
}

Pagination

All list endpoints support pagination. The response includes pagination metadata:

var circuits = await _client.GetCircuitsAsync(page: 1);

Console.WriteLine($"Page {circuits.Metadata.CurrentPage} of {circuits.Metadata.TotalPages}");
Console.WriteLine($"Total items: {circuits.Metadata.Count}");
Console.WriteLine($"Page size: {circuits.Metadata.PageSize}");

// Navigate to next page
if (circuits.Metadata.NextUrl != null)
{
    var nextPage = await _client.GetCircuitsAsync(page: circuits.Metadata.CurrentPage + 1);
}

Configuration Options

public sealed class JolpicaF1Options
{
    public string BaseUrl { get; set; } = "https://api.jolpi.ca";
    public string? ApiToken { get; set; }
    public TimeSpan Timeout { get; set; } = TimeSpan.FromSeconds(30);
}

Building and Packaging

Build

dotnet build

Pack for NuGet

dotnet pack -c Release

The package will be created in src/Jolpica.F1/bin/Release/.

Sample Application

See the samples/Jolpica.F1.Sample project for a complete working example.

Endpoint Coverage

This library covers 100% of the endpoints defined in the OpenAPI specification:

• ✅ All data dump endpoints
• ✅ All F1 alpha core endpoints (circuits, drivers, laps, pit stops, rounds, session entries, sessions, teams)
• ✅ All schedule endpoints

All endpoints are mapped from their operationId in the OpenAPI spec to intuitive method names following .NET naming conventions.

Requirements

• .NET 8.0 or later
• No external heavy dependencies (only Microsoft.Extensions.* and System.Text.Json)

License

MIT

Author

Jordy van Eijk

Repository

https://github.com/jolpica/jolpica-f1-api-client