User Interface API Developer Guide
j
No Results
Search Tips:
- Please consider misspellings
- Try different search keywords
Prevent Record Duplication with Idempotent Record Writes
To make a request idempotent, include an Idempotency-Key value in your request header. By making a request idempotent, your records on the server remain in the same state even if an identical request is made once or multiple times. Salesforce uses server storage to store the cached response of an idempotent request.
Only the /ui-api/records/{recordId} resource supports idempotent record writes for the POST, PATCH, and DELETE methods. The following table describes idempotent record write support for specific UI API resources.
When a unique Idempotency-Key request header is passed to a supported resource, the response for a server data mutation operation is stored. Subsequently, next time a request is sent to the same resource with the same Idempotency-Key value, the cached response is returned instead of performing a server data mutation operation.
Idempotent record writes save server processing costs by returning cached response for POST, PATCH, and DELETE operations.
Include an Idempotency Key Value
In your request header, pass in an Idempotency-Key value in the UUID v4 format. You can use a library that supports UUID v4 generation, including the Java UUID utility.
curl --location --request POST 'https://MyDomainName.my.salesforce.com/services/data/v56.0/ui-api/records' \
--header 'Authorization: Bearer AuthToken' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 12cfe4e6-e477-4de8-aa4e-95d31aa2be24' \
--header 'Cookie: BrowserId=yVVAfz9GEeuRCtc5jOsncA; CookieConsentPolicy=0:0' \
--data-raw '{
"apiName": "ResourceAbsence",
"fields": {
"CreatedDate": "2022-12-01T14:52:16.000Z",
"LastModifiedDate": "2022-12-01T14:52:16.000Z",
"ResourceId": "0Hnxx0000004C92CAE",
"Start": "2022-12-02T14:52:16.000Z",
"End": "2022-12-03T14:52:16.000Z"
}
}'
When the idempotency key expires after 30 days, the cached record that’s associated with the idempotency key is deleted. If the same idempotency key is used again after it’s deleted, the key is treated as a new idempotency key. A new cached response is then stored when an idempotent request is received the first time.
Example: Upload a File With An Idempotency Key
Let’s look at how you can upload a file using an idempotency key. To send the idempotent request, include Idempotency-Key in your request header.
curl -H "X-PrettyPrint: 1" \
-F 'json={"title":"Example image", "description":"Your description"}' \
-F "fileData=@image.jpg;type=application/octet-stream" \
-X POST https://MyDomainName.my.salesforce.com/services/data/v58.0/ui-api/records/content-documents/content-versions \
-H 'Authorization: Bearer AuthToken' \
-H 'Idempotency-Key: YourKey'When you send the request, notice the id values in the contentDocument, contentDocumentLinks, and contentVersion fields. If you resend the request using the same idempotency key, the response is returned without any server-side operations and the id values remain the same, indicating that the file doesn’t get uploaded a second time.
HTTP Status Error Codes
An idempotent request returns 2XX status codes for a successful operation. It can also return one of these HTTP status error codes.
- 400
- You can receive one of the following errors.
- Idempotency not supported—Remove the Idempotency-Key header and retry the operation.
- Idempotency-Key is not in valid format—Generate a new Idempotency-Key header value and retry the operation.
- 422
- The Idempotency-Key header value is already used by the same user for a different request. Generate a new Idempotency-Key value and retry the operation.
- 409
- Either a different user has issued the same request earlier or this duplicate request is issued within a short time because an earlier request terminated abruptly. If you include a Retry-After header, a follow-up request is sent.
- 5XX
- A server error has occurred. If you include a Retry-After header, a follow-up request is sent.