Sichere Änderungen und Wiederholungen

Flachen Datensatz-Payload senden#

Erstellen Sie mit POST /{resource}, aktualisieren Sie mit PATCH /{resource}/{id}. Senden Sie Feldwerte direkt im JSON-Objekt, ohne fields-Hülle. PATCH ändert nur angegebene Felder. Beschreiben Sie zuerst die Ressource für Pflichtfelder und gültige Optionen. Die Beispiele verwenden ein Unternehmen Northfold; Ihr Arbeitsbereich kann zusätzliche Pflichtfelder verlangen.

• Erstellung liefert 201, { data: record } und einen Location-Header.
• Aktualisierung liefert 200 und { data: record }.
• Unbekannte Felder und ungültige Werte werden abgelehnt statt stillschweigend akzeptiert.
• Schreiben erfordert einen write-Schlüssel sowie Schreibrechte des Eigentümers auf Ressource und Felder.

# Set IDEMPOTENCY_KEY once for this logical operation; keep it for retries.
read -r -p 'Unique operation key: ' IDEMPOTENCY_KEY
curl --fail-with-body --include --request POST "$SQUARIO_API_BASE/companies" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{"name":"Northfold"}'

# Use the actual id returned by creation and a new key for this operation.
read -r -p 'Company id: ' COMPANY_ID
read -r -p 'Unique update operation key: ' UPDATE_KEY
curl --fail-with-body --request PATCH "$SQUARIO_API_BASE/companies/$COMPANY_ID" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $UPDATE_KEY" \
  --data '{"name":"Northfold Studio"}'

Benutzerdefinierte Felder nach Schlüssel schreiben#

Nutzen Sie flache cf__<key>-Eigenschaften oder ein einzelnes custom_fields-Objekt. Mischen Sie die Formate nicht in einer Anfrage. Ersetzen Sie integration_code im Beispiel durch einen echten schreibbaren Feldschlüssel aus dem Arbeitsbereichsschema. Pflicht- und bedingte Feldregeln werden serverseitig durchgesetzt.

{
  "custom_fields": {
    "integration_code": "northfold-001"
  }
}

Archivieren statt endgültig löschen#

DELETE /{resource}/{id} archiviert den Datensatz. Dies ist eine reversible Löschung; optional ist ein JSON-Anfragekörper { reason } möglich. Stellen Sie mit POST /{resource}/{id}/restore wieder her. Beide liefern den resultierenden Datensatz in data. Aktive Listen schließen Archive aus, außer mit include_archived=true.

read -r -p 'Unique archive operation key: ' ARCHIVE_KEY
curl --fail-with-body --request DELETE "$SQUARIO_API_BASE/companies/$COMPANY_ID" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $ARCHIVE_KEY" \
  --data '{"reason":"Integration cleanup"}'

read -r -p 'Unique restore operation key: ' RESTORE_KEY
curl --fail-with-body --request POST "$SQUARIO_API_BASE/companies/$COMPANY_ID/restore" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header "Idempotency-Key: $RESTORE_KEY"

Schreibwiederholungen bewusst gestalten#

Jede Datensatzänderung und Beziehungs-PUT/DELETE akzeptiert Idempotency-Key. Erzeugen Sie einen eindeutigen Schlüssel pro logischer Operation, speichern Sie ihn mit der Operation und verwenden Sie ihn bei Wiederholungen. Er enthält 1–255 druckbare ASCII-Zeichen ohne Leerzeichen und ist an den API-Schlüssel gebunden. Der Fingerprint umfasst Methode, /v1-Pfad, Querystring und exakte Anfragekörperbytes.

Unsicheres Ergebnis berücksichtigen#

Idempotenz reduziert Duplikate, garantiert aber keine exakt einmalige Ausführung. Ein unabgeschlossener Claim kann nach fünf Minuten übernommen werden; eine kurz vor Ausfall bestätigte Änderung kann erneut laufen. Wiederholen Sie nach unklarem Fehler mit ursprünglichem Schlüssel und Bytes und prüfen Sie danach den Datensatz vor einer neuen Operation. Lesezugriffe ignorieren den Header; nur erfolgreiche Antworten werden gespeichert.