TadoNetApi

Key Capabilities

The SDK provides a clean abstraction over the Tado API, allowing developers to interact with endpoints through structured services rather than low-level HTTP calls. Authentication is handled internally, removing the need to repeatedly implement OAuth flows, while strongly-typed models ensure predictable and maintainable data handling.

Developers can work with a consistent API surface that aligns with standard .NET patterns, making the SDK intuitive to integrate into both small projects and larger production systems.

Architecture & Design

The project is structured around clean architecture principles, separating responsibilities between API clients, services, and domain models. This ensures the SDK remains modular, testable, and easy to extend.

Rather than tightly coupling functionality, each layer is designed to operate independently, allowing the SDK to be reused across different types of .NET applications. Dependency injection is supported, making integration into modern ASP.NET Core systems straightforward.

Authentication & API Handling

Authentication is handled using OAuth2, with the SDK managing token acquisition, renewal, and request lifecycle internally. This removes a significant amount of boilerplate typically required when integrating with third-party APIs.

The HTTP layer is abstracted behind a clean service interface, ensuring that error handling, retries, and request formatting are managed consistently across all API interactions.

The Playground

Alongside the SDK, a dedicated playground environment is included to provide a practical way to explore and test the API.

Rather than simulating responses or using mocked data, the playground connects directly to the Tado API and executes a full authentication and data retrieval flow using OAuth device authorisation.

What the Playground Fetches

The playground retrieves a complete snapshot of a real Tado installation, including:

- User identity and account details
- Home configuration and system settings
- Active heating zones and their live status
- Temperature, humidity, and heating state per zone
- Device inventory (thermostats, sensors, bridge, receiver)
- Schedule configuration for each zone
- Mobile devices linked to presence detection
- Geolocation and occupancy state
- Live weather conditions for the home location

This creates a full hierarchical model of the smart home system — from user account level down to individual thermostat behaviour and live environmental readings.

Technical Implementation

The SDK is built using modern C# and .NET, focusing on clarity, maintainability, and predictable behaviour. API responses are mapped to strongly-typed models, ensuring consistency and reducing runtime errors.

A structured service layer provides a clear separation between API interaction and business logic, allowing developers to work with well-defined abstractions rather than raw data structures.

Testing & Quality

The project includes structured unit and integration testing to ensure reliability across API interactions.

Test coverage focuses on validating key integration points and ensuring consistent behaviour as the SDK evolves. This provides confidence that changes can be made safely without introducing regressions, while maintaining a predictable API surface for consumers.

Alongside local testing, the project is supported by a GitHub Actions-based CI pipeline, which automatically builds and validates the codebase on each commit. The workflow installs the required .NET SDK, restores dependencies, compiles the solution, and executes the full test suite as part of an automated validation process.

SDK Surface Definition

In addition to traditional documentation, the project includes a machine-readable representation of the SDK surface via sdk-surface.yaml.

This file provides a structured map of the SDK, including available methods, their signatures, and the primary models returned by each call. It acts as a companion to the README, offering a clear, programmatic view of how the SDK is structured and how it can be consumed.

This approach supports multiple use cases:

- Enables rapid understanding of the SDK without navigating source code
- Provides a consistent reference for contributors and integrators
- Allows tooling — including AI-assisted workflows — to reason about the SDK surface
- Supports future extensibility, such as automated documentation or client generation

By exposing the SDK contract in a structured format, the project moves beyond conventional documentation and towards a more formalised, tool-friendly interface definition.

Outcome

The result is a reusable .NET SDK that significantly reduces the effort required to integrate with the Tado platform.

It provides a clean, maintainable foundation for building applications that rely on external APIs, while also serving as a practical example of how to structure API wrappers using modern .NET practices.

Repository

View the full source code on GitHub:
https://github.com/untiedshoes/TadoNetApi