Veilige wijzigingen en retries

Een vlakke recordpayload sturen#

Maak aan met POST /{resource} en werk bij met PATCH /{resource}/{id}. Stuur veldwaarden rechtstreeks in een JSON-object, niet binnen een fields-wrapper. PATCH wijzigt alleen opgegeven velden. Beschrijf de resource eerst om verplichte velden en geldige opties te ontdekken. De voorbeelden gebruiken een bedrijf Northfold; je werkruimte kan extra verplichte velden vereisen.

• Aanmaken geeft 201, { data: record } en een Location-header.
• Bijwerken geeft 200 en { data: record }.
• Onbekende velden en ongeldige waarden worden geweigerd, niet stilzwijgend geaccepteerd.
• Schrijven vereist een write-sleutel en de resource- en veldschrijfrechten van de eigenaar.

# 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"}'

Aangepaste velden per key schrijven#

Gebruik vlakke cf__<key>-eigenschappen of één custom_fields-object. Combineer beide vormen niet in hetzelfde verzoek. Vervang integration_code in het voorbeeld door een echte schrijfbare veldkey uit je werkruimteschema. Verplichte en voorwaardelijke veldregels worden op de server afgedwongen.

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

Archiveren in plaats van permanent verwijderen#

DELETE /{resource}/{id} archiveert het record. Dit is een zachte verwijdering; je kunt optioneel een JSON-body { reason } meesturen. Herstel met POST /{resource}/{id}/restore. Beide geven het resulterende record in data. Actieve lijsten sluiten archieven uit tenzij je include_archived=true gebruikt.

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"

Bewust schrijfverzoeken herhalen#

Elke recordwijziging en relatie-PUT/DELETE accepteert Idempotency-Key. Genereer één unieke key per logische operatie, sla die bij de operatie op en hergebruik die voor retries. Deze bevat 1–255 afdrukbare ASCII-tekens zonder spaties en is gebonden aan de API-sleutel. De fingerprint omvat methode, /v1-pad, querystring en exacte bodybytes.

Een onzekere uitkomst voorzien#

Idempotentie vermindert dubbele wijzigingen, maar garandeert geen precies-eenmaaluitvoering. Een onafgeronde claim kan na vijf minuten worden overgenomen; een wijziging die net vóór uitval is vastgelegd kan opnieuw worden uitgevoerd. Herhaal na een dubbelzinnige fout met de oorspronkelijke key en bytes en controleer daarna het record voordat je een nieuwe operatie maakt. Leesoperaties negeren de header en alleen succesvolle antwoorden worden bewaard.