Skip to content

feat(spec): driveItem creation under drives/items/children + recursive paths#42

Open
dschmidt wants to merge 2 commits into
opencloud-eu:mainfrom
dschmidt:feat/create-folder
Open

feat(spec): driveItem creation under drives/items/children + recursive paths#42
dschmidt wants to merge 2 commits into
opencloud-eu:mainfrom
dschmidt:feat/create-folder

Conversation

@dschmidt
Copy link
Copy Markdown
Contributor

@dschmidt dschmidt commented May 11, 2026

Summary

  • Generalize the existing POST /v1beta1/drives/{drive-id}/root/children description from share-mounting only to the full MS Graph create-driveItem semantics (folder / file / remoteItem).
  • Add a sibling POST /v1beta1/drives/{drive-id}/items/{item-id}/children operation (operationId: CreateChildDriveItem) for creating items under a non-root parent.
  • Add @libre.graph.conflictBehavior query parameter (enum fail | replace) on both endpoints, controlling same-name child collisions. MS Graph's third value rename is omitted.
  • Document the MS Graph colon-syntax URL forms (/root:/{path}:/children and /items/{item-id}:/{path}:/children) in both operation descriptions. OpenAPI cannot express the colon-delimited path segment, so these URL forms aren't represented as separate operations.
  • Add @libre.graph.missingParentsBehavior query parameter (enum fail | create) as a libregraph extension controlling recursive creation of missing intermediate folders along a colon-syntax URL.

Notes

@libre.graph.conflictBehavior is a URL query parameter, not a body property. Following MS Graph's driveItem create docs: "The parameter @microsoft.graph.conflictBehavior should be included in the URL instead of the body of the request."

MS Graph is inconsistent on this across operations — its createUploadSession places the same annotation inside the request body (under item). This spec matches each operation's own MS Graph convention; the inconsistency is MS Graph's.

rename is omitted from the conflictBehavior enum. MS Graph defines fail | replace | rename. This spec exposes fail | replace only. The vendored reva exposes an overwrite primitive (net.ParseOverwrite, used in ocdav/{move,copy,put}.go) that maps naturally to replace. There is no equivalent helper for "pick a free name like foo (2).txt" — rename would require new server logic, not just wiring. Easier to add later than to spec a capability with no underlying primitive.

@libre.graph.missingParentsBehavior is a libregraph extension. No MS Graph equivalent. Controls whether the server auto-creates missing intermediate folders along a colon-syntax URL path. Default is fail (preserving current behavior); create opts into recursive creation.

dschmidt added 2 commits May 11, 2026 16:52
Broaden /v1beta1/drives/{drive-id}/root/children to describe the general
MS Graph create-driveItem semantics (folder/file/remoteItem) rather than
only share-mounting, and add a sibling
/v1beta1/drives/{drive-id}/items/{item-id}/children POST
(operationId: CreateChildDriveItem) for creation under a non-root parent.

Both endpoints accept a @libre.graph.conflictBehavior query parameter
(enum fail|replace, default fail) controlling same-name child collisions,
matching the MS Graph convention of passing conflict behavior in the URL
rather than the body. MS Graph's third value 'rename' is intentionally
omitted from this enum.
Document the MS Graph colon-syntax URL forms

    POST /v1beta1/drives/{drive-id}/root:/{path}:/children
    POST /v1beta1/drives/{drive-id}/items/{item-id}:/{path}:/children

on both create-item operations. OpenAPI cannot express the colon-delimited
path segment, so the URL forms aren't represented as separate operations,
but the description makes clear the server accepts them.

Add a @libre.graph.missingParentsBehavior query parameter (enum fail|create,
default fail) controlling recursive creation of missing intermediate
folders along a colon-syntax path. Libregraph extension; ignored for
non-colon URLs.
@dschmidt dschmidt marked this pull request as ready for review May 11, 2026 14:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant