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
POSTlegt an. Ein Kontakt antwortet201mit dem Objekt. Ein Inserat antwortet202mit 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, ist409.PATCHändert als Merge Patch (RFC 7396): Ein fehlendes Mitglied bleibt,nullleert es, ein Wert ersetzt es, eine Liste ersetzt die Liste. Was sich nicht leeren lässt, nimmt keinnull.PUT /v1/listings/{externalListingId}verlangt einen vollständigen Rumpf und ändert das Inserat dann wiePATCH: Was der Rumpf nicht nennt, bleibt,nullleert es. Eine unbekannte Id ist404; mitcreateIfMissing=truelegtPUTsie an.- Ein Mitglied, das die API nicht kennt, ist
400, underrors[].namenennt es. Nichts wird stillschweigend verworfen. - Der Rumpf ist JSON (
Content-Type: application/json, sonst415) und höchstens 512 KB (413). Die eine Ausnahme istPOST /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.
| Fall | Antwort |
|---|---|
| Gleicher Key, gleicher Rumpf, die erste Anfrage ist fertig | dieselbe Antwort noch einmal, mit dem Kopf Idempotent-Replayed: true |
| Gleicher Key, anderer Rumpf | 422, idempotency_key_reused |
| Die erste Anfrage läuft noch | 409, idempotency_key_in_use, mit Retry-After |
| Die erste Anfrage brach mitten in der Arbeit ab | 409, 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: beiGETund in der Antwort aufPOST,PATCHundPUT. 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,PUTundDELETEnehmenIf-Match. Steht der aktuelleETagin der Liste (mehrere, durch Kommas getrennt), läuft die Änderung. Sonst antwortet die API412mitprecondition_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
ETagzur selben Zeit ändern nicht beide, eine bekommt412. - Der Kopf ist optional. Ohne ihn schreibt die API ohne Prüfung.
- Bei
PUTauf ein Inserat ändertIf-Matchnur.If-None-Match: *legt nur an (412, wenn es schon existiert). - Bei
GETantwortetIf-None-Matchmit dem aktuellenETagmit304ohne 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
REST-API: Anmeldung mit einem API-Key
Jeder Aufruf von /v1 trägt einen API-Key als Bearer-Token. Wo du ihn bekommst, welche Scopes er trägt und was nicht geht.
REST-API: Inserate in der Form von OpenImmo 2.0
Inserate lesen und schreiben in der Form von OpenImmo 2.0. Zwei Ids, Entwürfe, Quittungen, Hinweise und jedes Mitglied eines Inserats.
REST-API: Fehler als Problem Details
Jeder Fehler von /v1 ist ein Problem nach RFC 9457 mit echtem HTTP-Status, einem Code zum Verzweigen und einer Request-Id für den Support.
REST-API: Limits und Drossel
Wie viele Aufrufe /v1 je Schlüssel und je Büro annimmt, welche Köpfe den Stand zeigen und was bei einem 429 zu tun ist.
Blättern
Jede Liste von /v1 liefert eine Seite und einen Weg zur nächsten. Inserate nutzen ein Page Token, die übrigen Ressourcen einen Cursor. Keine Gesamtzahl.
Ausgehende Nachrichten
Anfragenden antworten und nachfassen. Wann eine Nachricht sofort hinausgeht, wann ein Vorschlag auf ein Ja wartet (202) und wie du das Ergebnis liest.