Drive API v3: supported If-Match contract for media-only file replacement?

We are evaluating safe synchronization of one ordinary JSON file in a user’s My Drive, using the drive.file OAuth scope. We need to prevent a client working from an older copy from overwriting a newer saved copy.

The operation in question is only:

PATCH https://www.googleapis.com/upload/drive/v3/files/{fileId}?uploadType=media
Content-Type: application/json
If-Match: "<provider-issued-strong-etag>"

The If-Match header above is a proposed precondition whose support we are asking about, not a tested or documented Drive example. We have not run an authenticated Drive experiment. Resumable/multipart upload, metadata-only updates and Google Workspace document conversion are outside this question.

We reviewed the files.update reference, upload guide, files.get reference, File resource and performance guide. We could not establish the complete route-specific concurrency contract from those sources. We are not assuming that the absence of an etag JSON field proves the absence of an HTTP ETag header.

Could you point us to current Drive v3 documentation or an authoritative provider clarification covering these five points?

  1. Supported precondition: Does this exact media-replacement route support an exact If-Match entity-tag as a content-write precondition?
  2. Obtaining the validator: Which exact GET URL, query/representation and response header provide the strong validator? Does it cover content changes, how are the downloaded bytes paired with that same version, and is the tag valid on the upload URI?
  3. Concurrent enforcement: Is the comparison indivisible with committing the content? For example, clients A and B read the same base and submit different replacement bodies using its tag. After A commits, must B be rejected without replacing A’s bytes? We need to distinguish this guarantee from checking a version before a separate upload.
  4. Stale result: For an outdated tag and a distinct proposed body, what HTTP status and machine-readable reason are guaranteed? Are current bytes preserved? Are there any already-applied/2xx exceptions, and how can clients distinguish them from an ignored condition?
  5. Browser access: For Fetch from a permitted web origin, does preflight allow PATCH, Authorization, Content-Type and If-Match on this route? Is the validator exposed to JavaScript on the specified GET, and is the stale-condition response CORS-readable? Please identify any credentials-mode restrictions or differences from non-browser HTTP clients.

We are not treating an output-only version number, a checksum, a client-side version check, or a successful upload/readback as proof of stale-write protection. If this route has no supported conditional-content-write contract, an explicit clarification would also help us choose an appropriate design.

Thank you.

Hi Dear User,

Welcome to the Google Developer Forums!

Main Points of the Problem

  1. The Goal of Optimistic Concurrency Control (If-Match):

    • Developers typically use the HTTP If-Match header containing an ETag to ensure that a file update only proceeds if the server-side file version matches what the client expects. This prevents race conditions where concurrent updates might overwrite someone else’s changes.
  2. The Media-Only Update Limitation:

    • When executing a media-only file update or replacement in the Google Drive API v3 (e.g., updating just the binary payload using the /upload/drive/v3/files/{fileId} endpoint with uploadType=media), developers often notice that standard HTTP header behaviors or contract expectations around If-Match do not behave consistently or aren’t cleanly documented compared to metadata patches.
  3. API Contract Ambiguity:

    • The discussion highlights confusion over whether Google Drive’s media upload/replacement endpoints natively respect standard conditional request headers like If-Match for media-only binary uploads, or if developers are forced to use multipart/resumable upload flows to safely handle concurrency checks.

Useful Links & Resources to Solve the Problem

To properly handle file uploads, updates, and concurrency control in the Google Drive API v3, refer to the following official resources:

Thanking you,

Regards,

SOM

Thank you for outlining the issue and sharing the reference and upload guides. Could you help clarify these remaining points for an ordinary JSON file in My Drive, using drive.file and specifically PATCH https://www.googleapis.com/upload/drive/v3/files/{fileId}?uploadType=media?

  1. Supported condition: Does this exact media-only PATCH support If-Match with an exact strong ETag as a content-write precondition?
  2. Validator and bytes: Which GET URL/parameters and response header supply that strong ETag? How are the downloaded bytes tied to the same version, and is that ETag valid on the upload URI?
  3. Atomic enforcement: If A and B submit different bodies using the same base ETag, must B be rejected after A commits, without replacing A’s bytes? Is the comparison indivisible with committing the content?
  4. Stale response: What HTTP status and machine-readable reason are guaranteed, and are the current bytes preserved? Are there any already-applied/2xx exceptions for which clients need a separate check?
  5. Browser/CORS: Does preflight permit PATCH, Authorization, Content-Type and If-Match on this route? Can JavaScript read the validator on the specified GET and the stale-response status/body? Are there credentials-mode restrictions?

Could you point to documentation explicitly covering this route, or help obtain clarification from the Drive API team? If this route has no supported conditional-content-write contract, an explicit confirmation would also help. We have not run an authenticated Drive experiment.