1
0
mirror of https://github.com/laurent22/joplin.git synced 2024-12-09 08:45:55 +02:00
joplin/readme/spec/server_file_url_format.md

40 lines
1.3 KiB
Markdown
Raw Normal View History

2020-12-31 14:38:22 +02:00
# Structure of file URLs in Joplin Server
To identify a file, Joplin Server supports two types of URLs:
## Access by ID
**Format:** `BASE_URL/files/FILE_ID`
This is the simplest way and it matches how other API items are accessed by ID.
For example: `https://example.com/api/files/5c7e0f3f54434ba`
## Access by full path
**Format:** `BASE_URL/files/SPECIAL_DIR:/path/to/file/:`
This is to access a file by its full path. In this case, the path must be prefixed by `SPECIAL_DIR`, which can only be `root` at the moment. Then to differentiate the path from URL segments, it needs to be wrapped in colons `:`.
For example, to access the metadata of file `/my/file.txt`
`https://example.com/api/files/root:/my/file.txt:`
To access its content:
`https://example.com/api/files/root:/my/file.txt:/content`
To access the root only (for example to list its content):
`https://example.com/api/files/root:/:`
Which can also be written as:
`https://example.com/api/files/root`
## Difference between API and web app end points
The API and web app end points are consistent in the way they access files, except that in one case the URLs will start with `/api` and the other with just `/`. For example, this would access the same file:
- API: `https://example.com/api/files/root:/my/file.txt:`
- Web: `https://example.com/files/root:/my/file.txt:`