Einführung

Dies ist die API-Dokumentation für die Polyteia-Plattform.

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

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

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

{
    "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

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

Fehlerantwort

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

Fehlerbehandlung

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

{
    "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