Idempotent Payloads vs. ETag Conditional Requests for Safe Retries in Portainer API

Question

The goal is to safely retry failed API calls through Portainer without causing duplicate writes when interacting with the Docker daemon via the /api/endpoints/{id}/docker proxy.

Portainer documents that create/update operations are idempotent when the request includes a stable identifier, and that conditional requests using If‑Match/ETag prevent duplicate writes for mutable resources. However, the Docker proxy endpoint does not return a stable ETag in version 2.19.x, making the conditional retry mechanism unreliable, and ad‑hoc commands lack natural idempotency.

Should clients implement application‑level deduplication using unique request identifiers for proxy calls?
Is it acceptable to rely solely on idempotent endpoints for resource creation and use external locking or serialization for Docker proxy operations?
Can a wrapper layer generate and validate client‑side ETags for the proxy endpoint to restore conditional retry safety?

Tasadduq Burney · Answer

Recommended Strategy for Proxy Retries
For the /api/endpoints/{id}/docker proxy endpoint in Portainer 2.19.x, you should implement application-level deduplication using unique request identifiers. Because the Docker proxy does not return stable ETags, conditional requests (If-Match) cannot be used to ensure atomicity during retries.

Analysis of Proposed Approaches
The following table compares the viability of the three strategies mentioned in your request:

Approach
      Viability
      Reasoning

Application-level Deduplication
      High
      Most reliable way to prevent duplicate writes when the server lacks native idempotency tokens.

External Locking/Serialization
      Medium
      Effective for single-client scenarios, but risks race conditions or deadlocks in distributed environments.

Client-side ETag Wrapper
      Low
      Generating ETags on the client does not solve the server-side state problem; the proxy will still execute the command regardless of a client-generated tag.

Implementation Steps for Safe Retries

Assign a Request ID: Generate a UUID for every intended state-changing operation.
  State Tracking: Store this ID in a local or shared cache (e.g., Redis) with a status of PENDING.
  Execute Proxy Call: Send the request to the Portainer Docker proxy.
  Handle Failures: If a timeout or 5xx error occurs, check the state of the target resource via a GET request to the Docker API (e.g., checking for a container name) before retrying.
  Mark Completion: Update the request ID status to COMPLETED upon a successful 200/201 response.

Verification and Assumptions
This recommendation assumes you are operating on Portainer 2.19.x where the Docker proxy acts as a transparent pass-through to the Docker daemon. To verify the lack of ETag support, execute the following check:
curl -I https://your-portainer/api/endpoints/{id}/docker/containers
If the ETag header is missing from the response, conditional retries are functionally impossible for that endpoint.

Missing Diagnostic: Are your API clients distributed across multiple nodes or centralized in a single service? If distributed, external locking must be implemented via a distributed lock manager (DLM) rather than local memory.

Idempotent Payloads vs. ETag Conditional Requests for Safe Retries in Portainer API

1 answer

Recommended Strategy for Proxy Retries

Analysis of Proposed Approaches

Implementation Steps for Safe Retries

Verification and Assumptions

Your perspective belongs here.

0 question comments

Approach	Viability	Reasoning
Application-level Deduplication	High	Most reliable way to prevent duplicate writes when the server lacks native idempotency tokens.
External Locking/Serialization	Medium	Effective for single-client scenarios, but risks race conditions or deadlocks in distributed environments.
Client-side ETag Wrapper	Low	Generating ETags on the client does not solve the server-side state problem; the proxy will still execute the command regardless of a client-generated tag.