APIs and automation
Concurrent Writes in a File API: Preventing Overwrites and Resolving Conflicts
A general guide to detecting write races, checking whether the API documents conditional controls, coordinating updates, and recovering changes in a verifiable way.
What Is a Concurrent Overwrite?
Imagine that two processes, A and B, download the same file in state V1. A changes the title and saves a copy. Then B changes a number and saves its copy, which is still based on V1. If each write replaces the entire contents, the second write may erase A’s updated title. The result may look correct at first glance, even though one change has disappeared without notice.
The operations do not have to start at exactly the same time for a race to occur: they only need to overlap between the read and the write. The risk can arise when multiple integration workers, a person and an automated process, or separate tasks act on the same resource. The key question is not just who wrote last, but which version each update was based on.
The guidance below describes general design and troubleshooting patterns, not the behavior of any particular API or a guarantee about Apification. Check the capabilities and responses of the API you use before relying on them in an integration.
- Example: A reads V1; B reads V1; A saves V2; B saves its copy of V1 and may erase A’s change.
Recognize Risk in the Read-Modify-Write Flow
Map the path of each operation: how the process obtains the file, whether it modifies the entire contents or just part of them, how much time passes before it saves, and which response it treats as success. A full replacement operation deserves particular attention if the submitted copy is based on an earlier read. Risk can also arise when a process transforms documents outside the API and uploads the result later.
Look for potential overlaps: multiple jobs may act on the same identifier; there may be retries; different workflows may share resources; or updates may take time. As a general troubleshooting practice, record the affected resource, the origin of the operation, read and write times, and the result reported by the API. Do not log credentials or sensitive content.
- Map the possible writers for the resource, including users, scheduled processes, and retries.
- Check whether each operation replaces the entire file or applies a partial update.
Check the Contract Before Using ETag or If-Match
Before implementing a safeguard, consult the official documentation and OpenAPI contract for the specific API. Check whether the read response includes a version identifier or ETag and whether the write operation accepts a condition such as If-Match or another explicitly documented mechanism. The fact that a header exists in another API or appears in a code sample does not prove that the API you use supports it.
If the documentation confirms the mechanism, follow its instructions for obtaining and sending the version value and interpreting a rejection caused by stale state. The available evidence does not confirm that Apification supports ETag, If-Match, or another conditional control; do not assume they are available without checking the documentation for the applicable operation.
- Record which mechanism the API documents, where to obtain the version, and which response indicates a conflict.
- If there is no explicit documentation, treat conditional control as unconfirmed.
If No Conditional Control Is Documented, Consider Coordinating Writes
As a general integration pattern, you can coordinate the jobs sent by your own system to prevent two of them from writing to the same resource simultaneously. One option is a queue or lock keyed by identifier: activity can continue on different files, while only one job at a time is processed for each file. Define how order is preserved and what happens if a job fails or stalls.
This local coordination does not control users or other systems that write directly to the resource, and it is not a global guarantee. Also, do not automatically repeat a failed write without knowing its outcome: after a timeout, the client cannot always determine by itself whether the change was applied. Check the current state using the methods documented by the API before deciding what to do.
- If you use a queue, group jobs by resource and limit each group to one active coordinated writer.
- Set wait limits and a procedure for stopping and resuming processing.
- Avoid blind retries after a timeout.
Resolve a Conflict Without Erasing Valid Changes
If the API reports a conflict, or you detect that the state has changed since it was read, do not continue saving over the old copy. Read the available state again and compare it with the version the process used. If the changes affect independent parts and the API allows a safe update, prepare a new change based on the current state. If the changes are incompatible, preserve both proposals and request a decision from a person rather than silently choosing one.
An academic paper from the National Polytechnic School describes an implementation with version columns for detecting concurrent changes: if a change occurred after the read, another attempt could be forced or the conflict could be reported; in that implementation, conflicting simultaneous changes were rejected. This is an example of optimistic control in an application, not evidence that a file API or Apification implements that mechanism or returns the same responses. Source: Digital Library of the National Polytechnic School, https://bibdigital.epn.edu.ec/bitstream/15000/26284/1/CD14960.pdf.
As general guidance, keep a verifiable record of the observed state, the change being attempted, the reason for any retry or intervention, and the final outcome. Limit retries and read again before each authorized attempt. If you cannot safely compare or combine the contents, send the case for review.
- Read the current state again before rebuilding an update.
- Retry only after checking the new version and the applicable merge rules.
- Request human review when changes are incompatible or cannot be compared.
Test Races, Timeouts, and Late Responses
As a general integration test, set up two processes and coordinate them so both read the same state before attempting to save. Change a different part in each process and check whether the final result preserves both changes or one disappears. Repeat the test with the write order reversed. The result describes the behavior observed in that test environment; it does not prove that the API provides a specific mechanism.
Include cases with a delay before saving, a timeout after sending the request, a late response, and a retry. Check the final state with a new read and verify that the logs let you reconstruct the sequence. If the API documents a conditional control, also test its response when the version has changed. Do not treat a success response from the client, by itself, as proof that the final state is as expected.
- Test two reads of the same state and writes in both orders.
- Include a timeout, late response, and retry; inspect the final state after each scenario.
Use Cloud History for Recovery, Not Prevention
Apification Cloud lets you view an item’s history, download previous versions, and restore content. These features can be part of a recovery procedure: identify the item, review its history, download a relevant version for inspection, and decide whether it should be restored.
History does not prevent two processes from causing an overwrite, nor does it determine by itself what each writer intended. Before restoring, confirm that the selected version contains what you need and consider whether a later change should also be preserved. Do not assume the API exposes the same actions as Cloud: separately check which operations the API documents.
- Review or download the candidate version before restoring it.
- Treat restoration as content recovery, not as a way to coordinate writes.
Preproduction Checklist
Before deployment, confirm the read and write contract, possible writers, and the actual unit of update. Check whether a conditional mechanism is documented; if this is unconfirmed, decide whether local job coordination fits your workflow and keep its limitations in mind. Define how you will detect a conflict and when you need to reread, retry, or request a review.
Validate the recovery procedure with a test version and check that logs explain the outcome without exposing secrets. Test concurrency, reversed write order, timeouts, and late responses. Apification lets you integrate Cloud and its services through REST APIs, OpenAPI, and webhooks; the availability of a specific version control for an operation must be confirmed in that operation’s documentation.
- Contract reviewed; use ETag, If-Match, or another control only if documented.
- Local coordination, if used, has clearly defined scope and limitations.
- Conflicts, retries, timeouts, and late responses tested.
- Review and version-restoration procedure verified.
- Enough logging to audit the flow, without credentials or sensitive data.
Frequently asked questions
Can I use If-Match with any file API?
Do not assume so. Check that the API documentation says it supports this mechanism, explains how to obtain the version, and specifies which response it returns for a conflict.
Does coordinating writes eliminate all overwrite risk?
Not necessarily. A local queue can coordinate jobs that pass through it, but it does not by itself control users or other systems writing directly to the same resource.
Does Apification Cloud history prevent races?
No. Cloud lets you review history, download previous versions, and restore content. These features help with investigation and recovery, but they do not replace prevention or coordination of concurrent writes.
Sources and further reading
Documentation consulted while preparing this article.
- Documento académico de la Escuela Politécnica Nacional sobre control de concurrencia — Biblioteca Digital de la Escuela Politécnica Nacional
- Insuficiencia de evidencia para confirmar capacidades de Apification — Linkses
Explore Apification
Related articles
APIs and automation
Webhooks or Polling for Detecting File Changes: How to Choose
Compare notifications and periodic queries to choose a change-detection strategy that fits your latency, workload, and recovery needs.
APIs and automation
Decimal Differences in an API: How to Investigate Them Without Changing the Contract
A value-tracing example and two documented cases can help locate precision differences without assuming a cause or changing the contract.
APIs and automation
Out-of-Order Webhooks: How to Stop an Old Event from Reverting a File’s State
Receipt time does not prove which change happened first. Learn to review the webhook contract and reconcile file state using verifiable criteria.