Referenz für Transforms

Die API unter https://transforms.nimbusnexus.net/v1 legt Pipelines an, versioniert, testet und führt sie aus, nur für Ihren Workspace. Requests und Antworten sind JSON. Senden Sie einen Key als Authorization: Bearer <key> oder X-API-Key: <key> (Zugang erhalten). Timestamps sind ISO 8601 in UTC. Der Überblick erklärt das Produkt und Pipelines das Dokument.

Routen

read, write und admin sind unter Wer was darf erklärt.

Listen werden mit limit (1 bis 200, Standard 50) und offset (0 bis 10,000) paginiert. Die Antwort ist {"items": [...], "next_offset": <offset>}: Übergeben Sie next_offset als offset, um die nächste Seite zu erhalten. Auf der letzten Seite ist der Wert null. GET /v1/pipelines/templates ist die Ausnahme: Die Route nimmt weder limit noch offset entgegen und liefert alle Vorlagen auf einmal als einfaches Array.

Das Pipeline-Objekt

POST /v1/pipelines erwartet name und pipeline. Ein Dokument, das nie laufen könnte, wird mit 422 invalid_pipeline abgewiesen. Hat der Workspace bereits so viele Pipelines, wie sein Tarif erlaubt, lautet die Antwort 402 quota_exceeded, mit details.metric pipelines, details.limit und details.current.

Versionen

PATCH /v1/pipelines/{id} erwartet name, status, pipeline oder eine beliebige Kombination davon. Eine neue pipeline wird so geprüft wie beim Anlegen und als nächste Version gespeichert.

• Eine Version ändert sich nie, sodass ein Produkt seine Kopie anhand von ID und Version behalten kann.
• Wird derselbe Inhalt gespeichert, entsteht keine neue Version.
• Eine alte Version wiederherzustellen heißt, ihren Inhalt erneut zu speichern; sie wird damit zur neuesten.
• Aufbewahrt werden so viele Versionen, wie der Tarif vorsieht, die neuesten zuerst, und ein Speichern entfernt die ältesten darüber hinaus. Auch eine Version, die ein Produkt festschreibt, wird aufbewahrt, ebenso die fünf älteren Versionen, die wir in den letzten 30 Tagen zuletzt bei einem Produkt im Einsatz gesehen haben.

Jede Version in GET /v1/pipelines/{id}/versions hat version, created_by und created_at; GET /v1/pipelines/{id}/versions/{version} liefert zusätzlich ihre pipeline. Eine Version, die nicht mehr aufbewahrt wird, antwortet mit 404 not_found, pipeline_version.

Pipeline ausführen

POST /v1/pipelines/{id}/run wendet die aktuelle Version oder die aufbewahrte, die version nennt, auf das an, was Sie senden:

Vom Request wird nichts behalten, und die Ausführung wird gezählt. Die Antwort ist ein 200, gleich, was die Pipeline getan hat:

Dieselbe Pipeline schlägt beim selben Request auf dieselbe Weise fehl; wiederholen Sie ein failed daher nicht. Eine deaktivierte Pipeline antwortet mit 409 conflict, pipeline_disabled, und über der Rate des Tarifs oder bei zu vielen gleichzeitig laufenden Ausführungen oder Tests des Workspaces antwortet eine Ausführung mit 429 rate_limited, mit details.retry_after.

Dokument testen

POST /v1/pipelines/test erwartet pipeline, ein Dokument, das nicht gespeichert sein muss, mit body, headers und meta. Es wird so geprüft wie beim Speichern, läuft einmal und speichert und zählt nichts, teilt sich aber die Rate des Tarifs. Ein Verwerfen oder ein Fehlschlag ist ein 200, das genau das sagt.

Credential-Slots

Ein Slot ist das, was ein auth-Schritt nennt: eine ID und eine Bezeichnung, ohne Wert. Transforms speichert kein Credential, und keine Route nimmt eines entgegen. Ein Produkt, das die Pipeline per Referenz ausführt, ordnet dem Slot ein eigenes Secret zu (Credentials). POST /v1/slots erwartet label, bis zu 200 Zeichen, und antwortet mit 201:

PATCH /v1/slots/{id} erwartet label. DELETE /v1/slots/{id} antwortet mit 204 oder, solange die aktuelle Version einer Pipeline den Slot nennt, mit 409 conflict und details.reason slot_in_use, details.id und details.pipelines, der Anzahl der Pipelines. Hat der Workspace bereits so viele Slots, wie sein Tarif erlaubt, antwortet das Hinzufügen mit 402 quota_exceeded, mit details.metric slots.

Wer eine Pipeline ausführt

Ein Produkt verweist über die ID auf eine Pipeline und führt sie in seinem eigenen Prozess aus, mit seinen eigenen Secrets. Webhooks ist das erste: Transformationen. Jeder Abruf hält den Dienst und die Version fest, sodass eine gelesene Pipeline destinations und consumers zeigt.

Eine neue Version mit einem auth-Schritt erreicht beim Speichern jedes Produkt, das die Pipeline ausführt, und das Löschen der Pipeline ebenso. Jeder dieser Aufrufe muss in confirm_destinations jeden Dienst nennen, der eine Referenz hält oder den wir in den letzten 30 Tagen gesehen haben, im Body eines PATCH und in der Query eines DELETE. Andernfalls lautet die Antwort 409 conflict mit details.reason destinations_unconfirmed und details.destinations, und nichts ändert sich. Die eigenen URLs eines Dienstes stehen hier nie: Dieses Produkt verlangt für sie selbst dieselbe Bestätigung.

Wer was darf

Eine abgewiesene Aktion antwortet mit 403 forbidden und details.reason role, und details.required nennt die nötige Rolle. Ein Member darf eine Pipeline mit einem Credential-Schritt weiterhin umbenennen, ausführen und testen und den Schritt entfernen. Die Kontokonsole erstellt Keys mit Read und Read & write, und ein Key mit einem anderen Scope, etwa write, wird wie Read behandelt.

Transforms bedient ganze Workspaces. Ein Gastzugang oder ein Key, der auf ein Projekt beschränkt ist, wird mit 403 project_confined abgewiesen. Ein Workspace hat Transforms, sobald ein Owner oder Admin die Konsole geöffnet oder das Produkt über Add a product hinzugefügt hat. Bis dahin werden andere Mitglieder mit 403 product_not_enabled abgewiesen.

Tarife und Limits

GET /v1/plan gibt an, welche Limits gelten: plan, der hinterlegte Tarif; enforced_as, der Tarif, dessen Limits gelten, free, wenn es keinen gibt; ceilings, die Limits nach Namen; past_due, suspended und system.

Kurz nacheinander dürfen so viele Ausführungen eintreffen, wie in zehn Sekunden erlaubt sind, mindestens aber 10. Außerdem laufen für einen Workspace in jedem Serverprozess höchstens zwei Ausführungen oder Tests gleichzeitig, und was darüber hinaus eintrifft, wird nicht in eine Warteschlange gestellt, sondern mit 429 rate_limited und details.retry_after 1 abgewiesen. GET /v1/usage gibt an, wie viel verbraucht ist: period, der Monat, angegeben als sein erster Tag; runs, failures und dropped dieses Monats, über die Ausführungs-API; pipelines, gemessen an max_pipelines; und slots, die vorhandenen Slots, gemessen an max_secret_slots. Ausführungen werden gezählt, nicht abgerechnet, und eine Ausführung in einem Produkt, das auf die Pipeline verweist, zählt zum Verbrauch dieses Produkts.

Solange eine Zahlung offen ist, werden Änderungen mit 402 workspace_frozen abgewiesen, und Ausführungen und Tests laufen weiter. Endet die Nachfrist, werden auch Ausführungen und Tests abgewiesen, mit 402 workspace_suspended. Lesen und Löschen bleiben möglich.

Fehler

Die Fehler der API verwenden das unter Fehler beschriebene Format.

Ungültige Pipelines

Die Ablehnung nennt das erste Problem: details.reason, details.path (ein JSON Pointer darauf) und details.step (ab 0 gezählt), jeweils sofern zutreffend.

{ "error": { "code": "invalid_pipeline", "message": "…", "details": { "reason": "credential_header", "path": "/steps/0/headers/set/Authorization", "step": 0 }, "request_id": "…" } }

Behandeln Sie reason als offenen String und sehen Sie einen Standardfall für Werte vor, die Sie nicht kennen.

Nächste Schritte

• Schnellstart — eine Pipeline testen, speichern und ausführen.
• Pipelines — jeder Schritt, Pfad und Filter und jede Vorlage.
• Transforms-API — jede Operation, mit dem Request in curl, TypeScript, Python oder Go.
• Fehler — das Fehlerformat, jedes Feld in details und ein Muster für den Umgang damit.