AthausDocs

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

  • POST creates. A contact answers 201 with the object. A listing answers 202 with a receipt (Listings). A POST never changes what exists: an email address, an address with its unit or a reference the office already has is 409.
  • PATCH changes as a merge patch (RFC 7396): a missing member stays, null clears it, a value replaces it, a list replaces the list. What cannot be cleared takes no null.
  • PUT /v1/listings/{externalListingId} needs a complete body and then changes the listing like PATCH: what the body does not name stays, null clears it. An unknown id is 404; with createIfMissing=true PUT creates it.
  • A member the API does not know is 400, and errors[].name names it. Nothing is silently dropped.
  • The body is JSON (Content-Type: application/json, else 415) and at most 512 KB (413). The one exception is POST /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.

CaseAnswer
Same key, same body, the first request is donethe same answer again, with the header Idempotent-Replayed: true
Same key, a different body422, idempotency_key_reused
The first request is still running409, idempotency_key_in_use, with Retry-After
The first request ended in the middle of its work409, 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: in GET, and in the answer to POST, PATCH and PUT. 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, PUT and DELETE accept If-Match. If the current ETag is in the list (several separated by commas), the change runs. Otherwise the API answers 412 with precondition_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 ETag at the same time do not both change it, one gets 412.
  • The header is optional. Without it, the API writes without checking.
  • On PUT of a listing, If-Match only changes. If-None-Match: * only creates (412 if it exists already).
  • On GET, If-None-Match with the current ETag answers 304 without 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

On this page