# API Referenz

Vollständige API-Dokumentation für Questra Data.

## Hauptklassen

### High-Level API

- [**QuestraData**](highlevel-client.md) - High-Level Client für einfache Operationen

### Low-Level API

- [**QuestraDataCore**](client.md) - Low-Level Client mit direktem Zugriff
- [**Queries**](queries.md) - GraphQL Queries (Lesen)
- [**Mutations**](mutations.md) - GraphQL Mutations (Schreiben)
- [**REST Operationen**](rest-operations.md) - REST API für TimeSeries, Files, Audit

## Models

### Inventory Models

- [**Inventory Models**](models-inventory.md) - Inventory, InventoryProperty, InventoryRelation, etc.

### TimeSeries Models

- [**TimeSeries Models**](models-timeseries.md) - TimeSeriesValue, Quality, Aggregation, etc.

### REST Models

- [**REST Models**](models-rest.md) - TimeSeriesData, File, ProblemDetails, etc.

### Permission Models

- [**Permission Models**](models-permissions.md) - Permissions, Roles, Privileges

## Schnellnavigation

=== "High-Level API"

    ```python
    from questra_data import QuestraData

    client = QuestraData(
        graphql_url="https://dev.example.com/graphql",
        auth_client=auth_client
    )

    # CRUD Operationen
    items = client.list("Stromzaehler", "Energie")
    item = client.create("Stromzaehler", "Energie", properties={...})
    client.update("Stromzaehler", "Energie", item_id="...", properties={...})
    client.delete("Stromzaehler", "Energie", item_id="...")

    # Zeitreihen
    result = client.list_timeseries_values(...)
    client.save_timeseries_values(...)

    # Verwaltung
    client.create_namespace(...)
    client.create_inventory(...)
    ```

=== "Low-Level API"

    ```python
    from questra_data import QuestraDataCore

    client = QuestraDataCore(
        graphql_url="https://dev.example.com/graphql",
        auth_client=auth_client
    )

    # GraphQL Queries
    inventories = client.queries.get_inventories()
    namespaces = client.queries.get_namespaces()

    # GraphQL Mutations
    client.mutations.create_namespace(...)
    client.mutations.upsert_item(...)

    # REST API
    data = client.timeseries.get_data(...)
    client.files.upload(...)

    # Raw GraphQL
    result = client.execute_raw("query { ... }")
    ```

=== "Models"

    ```python
    from questra_data import (
        # Inventory Models
        Inventory,
        InventoryRelation,
        Namespace,

        # Property-Klassen (empfohlen)
        StringProperty,
        IntProperty,
        BoolProperty,
        # ... weitere Property-Klassen

        # TimeSeries Models
        TimeSeriesValue,
        Quality,
        Aggregation,

        # Enums
        DataType,
        RelationType,
        ConflictAction,
    )

    # Typsichere Property-Definition mit spezialisierten Klassen
    property = StringProperty(
        propertyName="Name",
        maxLength=200,
        isRequired=True
    )
    ```

## Konventionen

### Rückgabewerte

Die API verwendet konsequent typisierte Rückgabewerte:

- **High-Level API**: Python-native Typen (`list`, `dict`) oder dataclasses
- **Low-Level API**: dataclasses oder `dict` für Raw Queries

### Parameter-Naming

- **snake_case**: Python Methoden und Parameter (`inventory_name`, `from_time`)
- **camelCase**: GraphQL Felder (`propertyName`, `dataType`)

### Error Handling

Alle API-Methoden können folgende Exceptions werfen:

- `requests.exceptions.HTTPError` - HTTP-Fehler
- `gql.transport.exceptions.TransportQueryError` - GraphQL-Fehler
- `ValueError` - Ungültige Parameter

Siehe [Error Handling Guide](../guides/error-handling.md) für Details.

## Weitere Ressourcen

- [Quickstart](../getting-started/quickstart.md) - Erste Schritte
- [API-Übersicht](../getting-started/api-overview.md) - High-Level vs Low-Level
- [Best Practices](../guides/best-practices.md) - Empfehlungen
