AthausDoku

REST-API: Schreiben und Idempotenz

Inserate und Kontakte anlegen, ändern und löschen. Merge Patch, Idempotency-Key für sichere Wiederholungen, ETag und If-Match gegen Überschreiben.

Zuletzt aktualisiert:

Mit POST, PATCH, PUT und DELETE schreibt dein System listings und contacts im Büro. Der API-Key braucht den Scope propose und die Stufe write auf der Ressource (Scopes und Stufen). Ein Key mit nur dem Scope read bekommt 403 und insufficient_permissions; es wird nichts geschrieben.

Was du schreibst, wird im Büro und in der Historie des Eintrags unter dem Namen des Keys festgehalten. Eine Änderung über die API fließt nie in ein angebundenes CRM zurück.

Anlegen und ändern

  • POST legt an. Ein Kontakt antwortet 201 mit dem Objekt. Ein Inserat antwortet 202 mit einer Quittung (Inserate). Ein POST ändert nie, was es schon gibt: Eine E-Mail-Adresse, eine Adresse samt Wohnung oder eine Referenz, die das Büro schon hat, ist 409.
  • PATCH ändert als Merge Patch (RFC 7396): Ein fehlendes Mitglied bleibt, null leert es, ein Wert ersetzt es, eine Liste ersetzt die Liste. Was sich nicht leeren lässt, nimmt kein null.
  • PUT /v1/listings/{externalListingId} verlangt einen vollständigen Rumpf und ändert das Inserat dann wie PATCH: Was der Rumpf nicht nennt, bleibt, null leert es. Eine unbekannte Id ist 404; mit createIfMissing=true legt PUT sie an.
  • Ein Mitglied, das die API nicht kennt, ist 400, und errors[].name nennt es. Nichts wird stillschweigend verworfen.
  • Der Rumpf ist JSON (Content-Type: application/json, sonst 415) und höchstens 512 KB (413). Die eine Ausnahme ist POST /v1/medias: Dort ist der Rumpf die Datei, höchstens 25 MB (Fotos und Dokumente).

Löschen

Ein DELETE auf einen Kontakt antwortet 200 mit { "object": "contact", "id": "...", "deleted": true }. Ein DELETE auf ein Inserat antwortet 202 mit einer Quittung. Ein Inserat mit anstehenden Besichtigungen ist 409 (upcoming_viewings_exist): Löschen würde die Besichtigungen absagen, und das verlässt das Haus. Auch ein veröffentlichtes Inserat und ein laufender Maklervertrag halten das Löschen auf (listing_active, brokerage_agreement_active).

Wiederholen, ohne doppelt zu schreiben

Schicke bei jedem POST den Kopf Idempotency-Key mit einem Zufallswert (zum Beispiel eine UUID, 1 bis 255 Zeichen). PUT und DELETE nehmen ihn auch.

FallAntwort
Gleicher Key, gleicher Rumpf, die erste Anfrage ist fertigdieselbe Antwort noch einmal, mit dem Kopf Idempotent-Replayed: true
Gleicher Key, anderer Rumpf422, idempotency_key_reused
Die erste Anfrage läuft noch409, idempotency_key_in_use, mit Retry-After
Die erste Anfrage brach mitten in der Arbeit ab409, idempotency_outcome_unknown

Gespeichert werden nur Erfolge, 24 Stunden lang, getrennt nach API-Key und Operation. Nach einem Fehler ist der Key wieder frei. Bei idempotency_outcome_unknown weiß niemand, ob etwas geschrieben wurde: Sieh nach, was da ist, und wiederhole mit einem neuen Key.

Der Kopf ist hier optional. Bei Operationen, die das Büro verlassen, ist er Pflicht (Was das Büro verlässt).

Nicht überschreiben: ETag und If-Match

Eine Person kann in der App etwas ändern, während dein System noch mit dem alten Stand arbeitet. Mit If-Match ändert oder löscht dein System nur, wenn der Stand noch der ist, den es gelesen hat.

  • Jede einzelne Ressource trägt den Kopf ETag: bei GET und in der Antwort auf POST, PATCH und PUT. Er ändert sich mit jeder Änderung, die die API zeigt, auch mit einer, die eine Person in der App machte. Listen haben keinen. Behandle den Wert als undurchsichtig und schick ihn unverändert zurück, mit seinen Anführungszeichen.
  • PATCH, PUT und DELETE nehmen If-Match. Steht der aktuelle ETag in der Liste (mehrere, durch Kommas getrennt), läuft die Änderung. Sonst antwortet die API 412 mit precondition_failed, und es wird nichts geschrieben. If-Match: * heißt: nur wenn das Objekt existiert. Ein schwacher Wert (W/"...") passt nie.
  • Prüfung und Änderung sind ein Schritt: Zwei Anfragen mit demselben ETag zur selben Zeit ändern nicht beide, eine bekommt 412.
  • Der Kopf ist optional. Ohne ihn schreibt die API ohne Prüfung.
  • Bei PUT auf ein Inserat ändert If-Match nur. If-None-Match: * legt nur an (412, wenn es schon existiert).
  • Bei GET antwortet If-None-Match mit dem aktuellen ETag mit 304 ohne Rumpf. Die Anfrage zählt gegen die Grenze fürs Lesen.
# 1. Lesen und den ETag merken
curl -si https://api.athaus.ai/v1/contacts/$ID -H "Authorization: Bearer $KEY" | grep -i '^etag'
# etag: "V1StGXR8_Z5jdHi6B-myTg"
# 2. Nur ändern, wenn sich nichts geändert hat
curl -s -X PATCH https://api.athaus.ai/v1/contacts/$ID \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H 'If-Match: "V1StGXR8_Z5jdHi6B-myTg"' \
  -d '{"phone": null, "city": "Potsdam"}'

Hat sich der Stand inzwischen geändert, antwortet die API:

{
  "type": "https://docs.athaus.ai/en/api/errors#precondition_failed",
  "title": "The condition of the request (If-Match or If-None-Match) does not hold for the current state of the resource, and nothing was written. Read the resource again, apply your change to the new state, and retry with the new ETag.",
  "status": 412,
  "detail": "The resource has changed since you read it.",
  "instance": "req_0f3a9c2b7d4e41a8b6c15e9d3a7f2b04",
  "errorSource": "headers",
  "code": "precondition_failed"
}

Lies das Objekt neu, wende deine Änderung auf den neuen Stand an und wiederhole mit dem neuen ETag. Ein nicht lesbarer Kopf ist 400 mit errorSource headers.

Grenzen

Schreiben hat einen eigenen Eimer: 2 Anfragen pro Sekunde, ein Stoß von 60, getrennt vom Lesen (Grenzen).

Weiter lesen

Auf dieser Seite