# Einführung

## API-Struktur

Die Polyteia-Plattform bietet eine umfassende API, die es ermöglicht, alle Funktionen der Plattform zu steuern. Die API basiert auf dem RPC-Kommunikationsprinzip.

### Warum RPC?

RPC (Remote Procedure Call) ist ein Protokoll, das es Programmen ermöglicht, Funktionen auf entfernten Systemen aufzurufen, ohne sich mit den Details der Netzwerkkommunikation befassen zu müssen. Polyteia hat sich für RPC statt REST aus folgenden Gründen entschieden:

* **Einfachheit**: RPC ermöglicht direkte Funktionsaufrufe zwischen Client und Server mit minimalem Aufwand. Während REST komplexe HTTP-Verben und Ressourcenhierarchien erfordert, bietet RPC eine intuitive Methode zur Übergabe von Parametern.
* **Leistung**: RPC reduziert die Anzahl der Netzwerkanfragen durch die Möglichkeit, mehrere Operationen in einem einzigen Aufruf zu bündeln. Zudem ist der Protokoll-Overhead geringer, da keine komplexe HTTP-Infrastruktur benötigt wird.
* **Typsicherheit**: Durch die Definition von Schnittstellen in IDL (Interface Definition Language) ermöglicht RPC automatische Codegenerierung und bietet eine verbesserte Typsicherheit sowie klarere Serviceverträge.
* **Flexibilität**: Im Gegensatz zu REST ist RPC nicht auf ein ressourcenorientiertes Modell beschränkt. Dies macht es besonders geeignet für komplexe Operationen, die sich nicht einfach in CRUD-Aktionen übersetzen lassen.

### Befehle und Abfragen

Die Polyteia-Plattform unterstützt zwei Arten von RPC-Aufrufen:

* **Befehle**: Mit Befehlen können Sie Ressourcen erstellen, ändern oder löschen. Sie dienen zur Modifikation des Plattformzustands.
* **Abfragen**: Abfragen ermöglichen das Lesen von Ressourcen und Informationen. Sie dienen zur Abfrage des aktuellen Plattformzustands.

#### Beispiel-Befehl

```bash
curl -X POST 'https://app.polyteia.com/api' \
    -header "Content-Type: application/json" \
    -header "Authorization: Bearer <your_access_token>" \
    --data '{
        "command": "create_dataset",
        "params": {
            "name": "Kundenliste",
            "solution_id": "sol_cv33u4n0i6q45p93i930",
            "description": "Kundenliste 4",
            "source": "https://example.com/dataset.csv",
            "slug": "kundenliste"
        }
    }'
```

#### Beispiel-Abfrage

```bash
curl -X POST 'https://app.polyteia.com/api' \
    -header "Content-Type: application/json" \
    -header "Authorization: Bearer <your_access_token>" \
    --data '{
        "query": "get_dataset",
        "params": {
            "id": "ds_cv4t2cf0i6q1gflvu4m0"
        }
    }'
```

### API-Endpunkt

Alle API-Anfragen werden an den Endpunkt `https://app.polyteia.com/api` gesendet. Die API unterstützt ausschließlich die `POST`-Methode.

#### Erforderliche Header

* `Content-Type: application/json`
* `Authorization: Bearer <your_access_token>`

#### Struktur der Anfrage

Jede Anfrage besteht aus einem JSON-Objekt mit folgenden Hauptfeldern:

* `command`: Der auszuführende Befehl
* `query`: Die auszuführende Abfrage
* `params`: Die spezifischen Parameter für den Befehl oder die Abfrage

Hinweis: Es muss entweder ein `command` oder eine `query` angegeben werden.

#### Beispiel-Anfrage

```json
{
    "command": "create_dataset",
    "params": {
        "name": "Kundenliste",
        "solution_id": "sol_cv33u4n0i6q45p93i930",
        "description": "Kundenliste 4",
        "source": "https://example.com/dataset.csv",
        "slug": "kundenliste"
    }
}
```

### Antwortformat

Alle API-Antworten werden im JSON-Format zurückgegeben. Das Antwortformat ist für alle Befehle und Abfragen einheitlich. Der HTTP-Statuscode ist in der Regel `200`, außer bei Authentifizierungsfehlern (`401`). Der tatsächliche Erfolg oder Misserfolg einer Anfrage wird im Antwort-Body angezeigt.

Jede Antwort enthält entweder ein `data`-Feld bei erfolgreicher Ausführung oder ein `error`-Feld bei Fehlern. Diese Felder geben detaillierte Informationen über das Ergebnis der Anfrage.

#### Erfolgreiche Antwort

```json
{
    "data": {
        "id": "ds_123456789",
        "name": "Kundenliste",
        "created_at": "2023-10-01T12:00:00Z"
    }
}
```

#### Fehlerantwort

```json
{
    "error": {
        "code": 500,
        "message": "internal error",
        "details": []
    }
}
```

### Fehlerbehandlung

Bei Fehlern enthält die Antwort ein `error`-Objekt mit folgenden Informationen:

```json
{
    "error": {
        "code": 500,
        "message": "internal error",
        "details": []
    }
}
```

#### Fehlercodes

* `400`: Bad Request - Die Anfrage enthält ungültige Parameter
* `401`: Unauthorized - Fehlende oder ungültige Authentifizierung
* `403`: Forbidden - Keine Berechtigung für die angeforderte Aktion
* `404`: Not Found - Die angeforderte Ressource existiert nicht
* `500`: Internal Server Error - Ein unerwarteter Fehler ist aufgetreten


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.polyteia.com/api-docs/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.