Skip to content

Add File Move Operation to PATCH Endpoint (only the relevant commits) #191

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Add File Move Operation to PATCH Endpoint (only the relevant commits) #191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
58f70cf
feat: implement file move operation
duquesnay Jul 8, 2025
f97a004
refactor: simplify PATCH endpoint validation logic
duquesnay Jul 8, 2025
7fbaf0a
feat: add path validation security and consistent error handling to f…
duquesnay Jul 8, 2025
3f6b44f
docs: Add OpenAPI documentation for file move operation
duquesnay Jul 8, 2025
6564048
Implement a custom MOVE HTTP method
mairas Oct 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 81 additions & 12 deletions docs/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,7 @@ paths:
^2c7cfa
```

## Append Content Below a Heading
## Append, Prepend, or Replace Content Below a Heading

If you wanted to append the content "Hello" below "Subheading 1:1:1" under "Heading 1",
you could send a request with the following headers:
Expand All @@ -220,7 +220,7 @@ paths:
The above would work just fine for `prepend` or `replace`, too, of course,
but with different results.

## Append Content to a Block Reference
## Append, Prepend, or Replace Content to a Block Reference

If you wanted to append the content "Hello" below the block referenced by
"2d9b4a" above ("More random text."), you could send the following headers:
Expand All @@ -233,7 +233,7 @@ paths:
The above would work just fine for `prepend` or `replace`, too, of course,
but with different results.

## Add a Row to a Table Referenced by a Block Reference
## Append, Prepend, or Replace a Row or Rows to/in a Table Referenced by a Block Reference

If you wanted to add a new city ("Chicago, IL") and population ("16") pair to the table above
referenced by the block reference `2c7cfa`, you could send the following
Expand Down Expand Up @@ -666,7 +666,7 @@ paths:
^2c7cfa
```

## Append Content Below a Heading
## Append, Prepend, or Replace Content Below a Heading

If you wanted to append the content "Hello" below "Subheading 1:1:1" under "Heading 1",
you could send a request with the following headers:
Expand All @@ -679,7 +679,7 @@ paths:
The above would work just fine for `prepend` or `replace`, too, of course,
but with different results.

## Append Content to a Block Reference
## Append, Prepend, or Replace Content to a Block Reference

If you wanted to append the content "Hello" below the block referenced by
"2d9b4a" above ("More random text."), you could send the following headers:
Expand All @@ -692,7 +692,7 @@ paths:
The above would work just fine for `prepend` or `replace`, too, of course,
but with different results.

## Add a Row to a Table Referenced by a Block Reference
## Append, Prepend, or Replace a Row or Rows to/in a Table Referenced by a Block Reference

If you wanted to add a new city ("Chicago, IL") and population ("16") pair to the table above
referenced by the block reference `2c7cfa`, you could send the following
Expand Down Expand Up @@ -1104,7 +1104,7 @@ paths:
^2c7cfa
```

## Append Content Below a Heading
## Append, Prepend, or Replace Content Below a Heading

If you wanted to append the content "Hello" below "Subheading 1:1:1" under "Heading 1",
you could send a request with the following headers:
Expand All @@ -1117,7 +1117,7 @@ paths:
The above would work just fine for `prepend` or `replace`, too, of course,
but with different results.

## Append Content to a Block Reference
## Append, Prepend, or Replace Content to a Block Reference

If you wanted to append the content "Hello" below the block referenced by
"2d9b4a" above ("More random text."), you could send the following headers:
Expand All @@ -1130,7 +1130,7 @@ paths:
The above would work just fine for `prepend` or `replace`, too, of course,
but with different results.

## Add a Row to a Table Referenced by a Block Reference
## Append, Prepend, or Replace a Row or Rows to/in a Table Referenced by a Block Reference

If you wanted to add a new city ("Chicago, IL") and population ("16") pair to the table above
referenced by the block reference `2c7cfa`, you could send the following
Expand Down Expand Up @@ -1668,6 +1668,8 @@ paths:
- "Vault Files"
get:
description: |
**Note:** This path also supports the WebDAV-style `MOVE` method for moving files. Specify the destination path in a `Destination` header. The MOVE method is not displayed in Swagger UI due to OpenAPI spec limitations, but is fully functional. See the raw openapi.yaml for complete MOVE documentation.

Returns the content of the file at the specified path in your vault should the file exist.

If you specify the header `Accept: application/vnd.olrapi.note+json`, will return a JSON representation of your note including parsed tag and frontmatter data as well as filesystem metadata. See "responses" below for details.
Expand Down Expand Up @@ -1700,6 +1702,73 @@ paths:
Return the content of a single file in your vault.
tags:
- "Vault Files"
move:
description: |
Moves a file from its current location to a new location specified in the Destination header. This operation preserves file history and updates internal links. The destination path must be provided in the Destination header following WebDAV conventions.
parameters:
- description: |
The new path for the file (relative to your vault root). Path must not contain ".." or start with "/" for security reasons.
in: "header"
name: "Destination"
required: true
schema:
format: "path"
type: "string"
- description: |
Path to the relevant file (relative to your vault root).
in: "path"
name: "filename"
required: true
schema:
format: "path"
type: "string"
responses:
"201":
content:
application/json:
schema:
properties:
message:
example: "File successfully moved"
type: "string"
newPath:
example: "another-folder/file.md"
type: "string"
oldPath:
example: "folder/file.md"
type: "string"
type: "object"
description: "File successfully moved"
"400":
content:
application/json:
schema:
"$ref": "#/components/schemas/Error"
description: |
Bad request - Missing Destination header, invalid destination path, or path traversal attempt.
"404":
content:
application/json:
schema:
"$ref": "#/components/schemas/Error"
description: "Source file does not exist."
"405":
content:
application/json:
schema:
"$ref": "#/components/schemas/Error"
description: |
Your path references a directory instead of a file; this request method is valid only for files.
"409":
content:
application/json:
schema:
"$ref": "#/components/schemas/Error"
description: "Destination file already exists."
summary: |
Move a file to a new location in your vault.
tags:
- "Vault Files"
patch:
description: |
Inserts content into an existing note relative to a heading, block refeerence, or frontmatter field within that document.
Expand Down Expand Up @@ -1760,7 +1829,7 @@ paths:
^2c7cfa
```

## Append Content Below a Heading
## Append, Prepend, or Replace Content Below a Heading

If you wanted to append the content "Hello" below "Subheading 1:1:1" under "Heading 1",
you could send a request with the following headers:
Expand All @@ -1773,7 +1842,7 @@ paths:
The above would work just fine for `prepend` or `replace`, too, of course,
but with different results.

## Append Content to a Block Reference
## Append, Prepend, or Replace Content to a Block Reference

If you wanted to append the content "Hello" below the block referenced by
"2d9b4a" above ("More random text."), you could send the following headers:
Expand All @@ -1786,7 +1855,7 @@ paths:
The above would work just fine for `prepend` or `replace`, too, of course,
but with different results.

## Add a Row to a Table Referenced by a Block Reference
## Append, Prepend, or Replace a Row or Rows to/in a Table Referenced by a Block Reference

If you wanted to add a new city ("Chicago, IL") and population ("16") pair to the table above
referenced by the block reference `2c7cfa`, you could send the following
Expand Down
85 changes: 85 additions & 0 deletions docs/src/lib/move.jsonnet
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
{
tags: [
'Vault Files',
],
summary: 'Move a file to a new location in your vault.\n',
description: 'Moves a file from its current location to a new location specified in the Destination header. This operation preserves file history and updates internal links. The destination path must be provided in the Destination header following WebDAV conventions.\n',
parameters: [
{
name: 'Destination',
'in': 'header',
description: 'The new path for the file (relative to your vault root). Path must not contain ".." or start with "/" for security reasons.\n',
required: true,
schema: {
type: 'string',
format: 'path',
},
},
],
responses: {
'201': {
description: 'File successfully moved',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
message: {
type: 'string',
example: 'File successfully moved',
},
oldPath: {
type: 'string',
example: 'folder/file.md',
},
newPath: {
type: 'string',
example: 'another-folder/file.md',
},
},
},
},
},
},
'400': {
description: 'Bad request - Missing Destination header, invalid destination path, or path traversal attempt.\n',
content: {
'application/json': {
schema: {
'$ref': '#/components/schemas/Error',
},
},
},
},
'404': {
description: 'Source file does not exist.',
content: {
'application/json': {
schema: {
'$ref': '#/components/schemas/Error',
},
},
},
},
'405': {
description: 'Your path references a directory instead of a file; this request method is valid only for files.\n',
content: {
'application/json': {
schema: {
'$ref': '#/components/schemas/Error',
},
},
},
},
'409': {
description: 'Destination file already exists.',
content: {
'application/json': {
schema: {
'$ref': '#/components/schemas/Error',
},
},
},
},
},
}
26 changes: 15 additions & 11 deletions docs/src/openapi.jsonnet
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
local Delete = import 'delete.jsonnet';
local Get = import 'get.jsonnet';
local Patch = import 'patch.jsonnet';
local Post = import 'post.jsonnet';
local Put = import 'put.jsonnet';
local Delete = import 'lib/delete.jsonnet';
local Get = import 'lib/get.jsonnet';
local Move = import 'lib/move.jsonnet';
local Patch = import 'lib/patch.jsonnet';
local Post = import 'lib/post.jsonnet';
local Put = import 'lib/put.jsonnet';

local ParamDay = import 'day.param.jsonnet';
local ParamMonth = import 'month.param.jsonnet';
local ParamPath = import 'path.param.jsonnet';
local ParamPeriod = import 'period.param.jsonnet';
local ParamYear = import 'year.param.jsonnet';
local ParamDay = import 'lib/day.param.jsonnet';
local ParamMonth = import 'lib/month.param.jsonnet';
local ParamPath = import 'lib/path.param.jsonnet';
local ParamPeriod = import 'lib/period.param.jsonnet';
local ParamYear = import 'lib/year.param.jsonnet';


std.manifestYamlDoc(
Expand Down Expand Up @@ -166,7 +167,7 @@ std.manifestYamlDoc(
'Vault Files',
],
summary: 'Return the content of a single file in your vault.\n',
description: 'Returns the content of the file at the specified path in your vault should the file exist.\n\nIf you specify the header `Accept: application/vnd.olrapi.note+json`, will return a JSON representation of your note including parsed tag and frontmatter data as well as filesystem metadata. See "responses" below for details.\n',
description: '**Note:** This path also supports the WebDAV-style `MOVE` method for moving files. Specify the destination path in a `Destination` header. The MOVE method is not displayed in Swagger UI due to OpenAPI spec limitations, but is fully functional. See the raw openapi.yaml for complete MOVE documentation.\n\nReturns the content of the file at the specified path in your vault should the file exist.\n\nIf you specify the header `Accept: application/vnd.olrapi.note+json`, will return a JSON representation of your note including parsed tag and frontmatter data as well as filesystem metadata. See "responses" below for details.\n',
parameters+: [ParamPath],
},
put: Put {
Expand All @@ -193,6 +194,9 @@ std.manifestYamlDoc(
description: 'Inserts content into an existing note relative to a heading, block refeerence, or frontmatter field within that document.\n\n' + Patch.description,
parameters+: [ParamPath],
},
move: Move {
parameters: Move.parameters + [ParamPath],
},
delete: Delete {
tags: [
'Vault Files',
Expand Down
10 changes: 10 additions & 0 deletions src/constants.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,16 @@ export const ERROR_CODE_MESSAGES: Record<ErrorCode, string> = {
[ErrorCode.InvalidSearch]: "The search query you provided is not valid.",
[ErrorCode.ErrorPreparingSimpleSearch]:
"Error encountered while calling Obsidian `prepareSimpleSearch` API.",
[ErrorCode.MissingDestinationHeader]:
"Destination header is required for MOVE operations.",
[ErrorCode.InvalidDestinationPath]:
"Destination path must be a file path, not a directory.",
[ErrorCode.PathTraversalNotAllowed]:
"Path traversal is not allowed. Paths must be relative and within the vault.",
[ErrorCode.DestinationAlreadyExists]:
"Destination file already exists.",
[ErrorCode.FileOperationFailed]:
"File operation failed. Check the error message for details.",
};

export enum ContentTypes {
Expand Down
Loading