REST API: writing and idempotency
Create, change and delete listings and contacts. Merge patch, Idempotency-Key for safe retries, ETag and If-Match against overwriting.
Last updated:
With POST, PATCH, PUT and DELETE your system writes listings and contacts in the office. The API key needs the scope propose and the level write on the resource (Scopes and levels). A key with only the scope read gets 403 and insufficient_permissions; nothing is written.
What you write is recorded in the office and in the history of the item under the name of the key. A change made through the API never flows back into a connected CRM.
Create and change
POSTcreates. A contact answers201with the object. A listing answers202with a receipt (Listings). A POST never changes what exists: an email address, an address with its unit or a reference the office already has is409.PATCHchanges as a merge patch (RFC 7396): a missing member stays,nullclears it, a value replaces it, a list replaces the list. What cannot be cleared takes nonull.PUT /v1/listings/{externalListingId}needs a complete body and then changes the listing likePATCH: what the body does not name stays,nullclears it. An unknown id is404; withcreateIfMissing=truePUTcreates it.- A member the API does not know is
400, anderrors[].namenames it. Nothing is silently dropped. - The body is JSON (
Content-Type: application/json, else415) and at most 512 KB (413). The one exception isPOST /v1/medias: there the body is the file, at most 25 MB (Photos and documents).
Delete
A contact DELETE answers 200 with { "object": "contact", "id": "...", "deleted": true }. A listing DELETE answers 202 with a receipt. A listing with upcoming viewings is 409 (upcoming_viewings_exist): deleting it would cancel the viewings, and that leaves the house. A published listing and a running brokerage agreement also stop the deletion (listing_active, brokerage_agreement_active).
Retry without writing twice
Send the header Idempotency-Key with a random value on every POST (for example a UUID, 1 to 255 characters). PUT and DELETE accept it too.
| Case | Answer |
|---|---|
| Same key, same body, the first request is done | the same answer again, with the header Idempotent-Replayed: true |
| Same key, a different body | 422, idempotency_key_reused |
| The first request is still running | 409, idempotency_key_in_use, with Retry-After |
| The first request ended in the middle of its work | 409, idempotency_outcome_unknown |
Only successes are stored, for 24 hours, separated by API key and operation. After an error the key is free again. With idempotency_outcome_unknown nobody knows whether something was written: look at what is there, and retry with a new key.
The header is optional here. For operations that leave the office it is required (What leaves the office).
Do not overwrite: ETag and If-Match
A person can change something in the app while your system still works with the old state. With If-Match your system changes or deletes only if the state is still the one it read.
- Every single resource carries the header
ETag: inGET, and in the answer toPOST,PATCHandPUT. It changes with every change the API shows, including one a person made in the app. Lists have none. Treat the value as opaque and send it back unchanged, with its quotation marks. PATCH,PUTandDELETEacceptIf-Match. If the currentETagis in the list (several separated by commas), the change runs. Otherwise the API answers412withprecondition_failed, and nothing is written.If-Match: *means: only if the object exists. A weak value (W/"...") never matches.- The check and the change are one step: two requests with the same
ETagat the same time do not both change it, one gets412. - The header is optional. Without it, the API writes without checking.
- On
PUTof a listing,If-Matchonly changes.If-None-Match: *only creates (412if it exists already). - On
GET,If-None-Matchwith the currentETaganswers304without a body. The request counts against the reading limit.
# 1. Read and keep the ETag
curl -si https://api.athaus.ai/v1/contacts/$ID -H "Authorization: Bearer $KEY" | grep -i '^etag'
# etag: "V1StGXR8_Z5jdHi6B-myTg"# 2. Change only if nothing changed
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"}'If the state has changed in the meantime, the API answers:
{
"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"
}Read the object again, apply your change to the new state, and retry with the new ETag. An unreadable header is 400 with errorSource headers.
Limits
Writing has its own bucket: 2 requests per second, a burst of 60, separate from reading (Limits).
Keep reading
REST API: authentication with an API key
Every call to /v1 carries an API key as a bearer token. Where to get one, which scopes it carries and what does not work.
REST API: listings in the OpenImmo 2.0 shape
Read and write listings in the shape of OpenImmo 2.0. Two ids, drafts, receipts, warnings, and every member of a listing.
REST API: errors as problem details
Every error from /v1 is an RFC 9457 problem with a real HTTP status, a code to branch on and a request id for support.
REST API: limits and throttling
How many calls /v1 accepts per key and per office, which headers show the state and what to do on a 429.
Pagination
Every list of /v1 returns one page and a way to the next. Listings use a page token, the other resources a cursor. No total count.
Outbound messages
Reply to and follow up with people who inquired. When a message goes out at once and when a proposal waits for a yes (202), and how to read the outcome.