Personal OneDrive: final If-Match semantics for updating an existing driveItem by ID

The published Microsoft Graph v1.0 contract does not guarantee final-boundary If-Match semantics for PUT /drives/{driveId}/items/{itemId}/content, nor does it publish an alternative OneDrive Personal deferred-commit operation that conditionally replaces an existing item by immutable ID.

Direct binary replacement

The documented existing-item operation is:

PUT /v1.0/drives/{driveId}/items/{itemId}/content
Authorization: Bearer {token}
Content-Type: application/octet-stream

<file bytes>

It is explicitly described as replacing an existing item addressed by itemId, and success returns the newly created or updated driveItem ^1^.

However, its request-header contract lists only Authorization and Content-Type. It does not document If-Match, a 412 Precondition Failed result, or when any validator would be evaluated. Consequently, no published operation-specific guarantee establishes that:

• the supplied eTag is compared atomically at the final replacement boundary;
• a stale eTag causes 412 with no content or version mutation;
• rename or move races remain bound to the same item;
• deletion causes failure without creation or rebinding;
• deletion and recreation at the same path cannot affect the operation.

The ID-form and path-form operations are documented separately: the ID form replaces an existing item, while the parent-ID/filename form uploads a new file ^1^. That distinction supports addressing the intended item by ID, but it is not a published concurrency or no-mutation guarantee.

Other DriveItem operations explicitly document If-Match and 412, demonstrating that such behavior is specified per operation. For example, the metadata update operation documents that contract ^2^. It cannot be transferred implicitly to the content-upload operation.

Upload sessions do not close the gap

An existing-item upload session can be created by immutable item ID:

POST /v1.0/drives/{driveId}/items/{itemId}/createUploadSession
Authorization: Bearer {token}
Content-Type: application/json
If-Match: "{frozen-etag}"

{
  "deferCommit": true
}

For this session-creation request, the documentation says a nonmatching eTag or cTag returns 412 Precondition Failed ^3^. Thus, it tests the current validator of the item identified by {itemId} when the session is created.

It does not say that this condition is retained and tested again when the session is committed. A successful creation-time comparison therefore does not protect against an edit, move, rename, deletion, or delete/recreate race occurring during byte upload.

With deferCommit: true, explicit completion differs by platform:

• OneDrive for Business and SharePoint: zero-length POST to the upload URL.
• OneDrive Personal: final PUT using the upload-error/explicit-commit mechanism ^3^.

The documented Personal recovery commit is path-oriented and supplies @microsoft.graph.sourceUrl:

PUT /v1.0/me/drive/root:/{path_to_parent}
Authorization: Bearer {token}
Content-Type: application/json
If-Match: "{etag-or-ctag}"

{
  "name": "file.dat",
  "@microsoft.graph.conflictBehavior": "fail",
  "@microsoft.graph.sourceUrl": "{upload-session-URL}"
}

Although the page says If-Match can be used on that call, it does not provide an equivalent:

PUT /drives/{driveId}/items/{existingItemId}

commit contract for OneDrive Personal. Nor does it specify that the path-oriented request’s If-Match tests the frozen eTag of the original existing file rather than the resource addressed by the commit request. @microsoft.graph.sourceUrl is documented as an instruction to download content from a URL during a PUT; that resource documentation does not add immutable-item or final compare-and-swap semantics ^4^.

Therefore, the path-oriented Personal commit must not be represented as the requested immutable-ID conditional replacement primitive.

Publication and ambiguous responses

The documentation establishes these observable states:

• Before commit, uploaded fragments remain in temporary session storage.
• With deferCommit, final publication requires an explicit request.
• A session-status GET returns its expiration and missing byte ranges.
• Successful completion returns 200 OK or 201 Created with the resulting driveItem ^3^.

It does not publish an idempotency key, transactional status resource, or receipt that distinguishes these cases after a timeout or lost final response:

1. the commit was definitely rejected before publication;
2. the commit succeeded but its response was lost;
3. processing remains indeterminate.

A returned precondition/error response can establish rejection only to the extent documented for that operation. A transport failure or missing response is unknown outcome, not definite nonpublication. Session status can identify missing ranges and permit upload resumption, but the documented uploadSession resource contains only uploadUrl, expirationDateTime, and nextExpectedRanges; it has no committed-result or destination-item field ^5^.

Post-failure reconciliation can read the original item by ID and inspect its current metadata/eTag, including a deleted item on OneDrive Personal with includeDeletedItems=true ^6^. That is an after-the-fact observation, not an atomic proof that a particular payload was or was not published; an application-level content hash or operation marker would be needed for stronger reconciliation.

The requested compare-and-swap contract therefore requires clarification from Microsoft Graph/OneDrive engineering or a documentation change. It cannot currently be derived from generic HTTP conditional-request semantics or from the neighboring Graph operations.

References

1. Upload or replace the contents of a driveItem
2. Update DriveItem properties
3. driveItem: createUploadSession
4. driveItem resource type
5. uploadSession resource type
6. Get driveItem