github.com/cozy/cozy-stack@v0.0.0-20240603063001-31110fa4cae1/docs/nextcloud.md (about) 1 [Table of contents](README.md#table-of-contents) 2 3 # Proxy for a remote NextCloud 4 5 The nextcloud konnector can be used to create an `io.cozy.account` for a 6 NextCloud. Then, the stack can be used as a client for this NextCloud account. 7 Currently, it supports files operations via WebDAV. 8 9 ## GET /remote/nextcloud/:account/*path 10 11 This route can be used to list the files and subdirectories inside a directory 12 of NextCloud. 13 14 With `Dl=1` in the query-string, it can also be used to download a file. 15 16 The `:account` parameter is the identifier of the NextCloud `io.cozy.account`. 17 It is available with the `cozyMetadata.sourceAccount` of the shortcut file for 18 example. 19 20 The `*path` parameter is the path of the file/directory on the NextCloud. 21 22 **Note:** a permission on `GET io.cozy.files` is required to use this route. 23 24 ### Request (list) 25 26 ```http 27 GET /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/Documents HTTP/1.1 28 Host: cozy.example.net 29 Authorization: Bearer eyJhbG... 30 ``` 31 32 ### Response (list) 33 34 ```http 35 HTTP/1.1 200 OK 36 Content-Type: application/vnd.api+json 37 ``` 38 39 ```json 40 { 41 "data": [ 42 { 43 "type": "io.cozy.remote.nextcloud.files", 44 "id": "192172", 45 "attributes": { 46 "type": "directory", 47 "name": "Images", 48 "updated_at": "Thu, 02 May 2024 09:29:53 GMT", 49 "etag": "\"66335d11c4b91\"" 50 }, 51 "meta": {}, 52 "links": { 53 "self": "https://nextcloud.example.net/apps/files/files/192172?dir=/Documents" 54 } 55 }, 56 { 57 "type": "io.cozy.remote.nextcloud.files", 58 "id": "208937", 59 "attributes": { 60 "type": "file", 61 "name": "BugBounty.pdf", 62 "size": 2947, 63 "mime": "application/pdf", 64 "class": "pdf", 65 "updated_at": "Mon, 14 Jan 2019 08:22:21 GMT", 66 "etag": "\"dd1a602431671325b7c1538f829248d9\"" 67 }, 68 "meta": {}, 69 "links": { 70 "self": "https://nextcloud.example.net/apps/files/files/208937?dir=/Documents" 71 } 72 }, 73 { 74 "type": "io.cozy.remote.nextcloud.files", 75 "id": "615827", 76 "attributes": { 77 "type": "directory", 78 "name": "Music", 79 "updated_at": "Thu, 02 May 2024 09:28:37 GMT", 80 "etag": "\"66335cc55204b\"" 81 }, 82 "meta": {}, 83 "links": { 84 "self": "https://nextcloud.example.net/apps/files/files/615827?dir=/Documents" 85 } 86 }, 87 { 88 "type": "io.cozy.remote.nextcloud.files", 89 "id": "615828", 90 "attributes": { 91 "type": "directory", 92 "name": "Video", 93 "updated_at": "Thu, 02 May 2024 09:29:53 GMT", 94 "etag": "\"66335d11c2318\"" 95 }, 96 "meta": {}, 97 "links": { 98 "self": "https://nextcloud.example.net/apps/files/files/615828?dir=/Documents" 99 } 100 } 101 ], 102 "meta": { 103 "count": 5 104 } 105 } 106 ``` 107 108 ### Request (download) 109 110 ```http 111 GET /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/Documents/Wallpaper.jpg?Dl=1 HTTP/1.1 112 Host: cozy.example.net 113 Authorization: Bearer eyJhbG... 114 ``` 115 116 ### Response (download) 117 118 ```http 119 HTTP/1.1 200 OK 120 Content-Type: image/jpeg 121 Content-Length: 12345 122 Content-Disposition: attachment; filename="Wallpaper.jpg" 123 124 ... 125 ``` 126 127 #### Status codes 128 129 - 200 OK, for a success 130 - 401 Unauthorized, when authentication to the NextCloud fails 131 - 404 Not Found, when the account is not found or the directory is not found on the NextCloud 132 133 ## PUT /remote/nextcloud/:account/*path 134 135 This route can be used to create a directory, or upload a file, on the 136 NextCloud. The query-string parameter `Type` should be `file` when uploading a 137 file. 138 139 The `:account` parameter is the identifier of the NextCloud `io.cozy.account`. 140 141 The `*path` parameter is the path of the file/directory on the NextCloud. 142 143 **Note:** a permission on `POST io.cozy.files` is required to use this route. 144 145 ### Request (directory) 146 147 ```http 148 PUT /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/Documents/Images/Clouds?Type=directory HTTP/1.1 149 Host: cozy.example.net 150 Authorization: Bearer eyJhbG... 151 ``` 152 153 ### Response (directory) 154 155 ```http 156 HTTP/1.1 201 Created 157 Content-Type: application/json 158 ``` 159 160 ```json 161 { 162 "ok": true 163 } 164 ``` 165 166 ### Request (file) 167 168 ```http 169 PUT /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/Documents/Images/sunset.jpg?Type=file HTTP/1.1 170 Host: cozy.example.net 171 Authorization: Bearer eyJhbG... 172 Content-Type: image/jpeg 173 Content-Length: 54321 174 175 ... 176 ``` 177 178 ### Response (file) 179 180 ```http 181 HTTP/1.1 201 Created 182 Content-Type: application/json 183 ``` 184 185 ```json 186 { 187 "ok": true 188 } 189 ``` 190 191 #### Status codes 192 193 - 201 Created, when the directory has been created 194 - 400 Bad Request, when the account is not configured for NextCloud 195 - 401 Unauthorized, when authentication to the NextCloud fails 196 - 404 Not Found, when the account is not found or the parent directory is not found on the NextCloud 197 - 409 Conflict, when a directory or file already exists at this path on the NextCloud. 198 199 ## DELETE /remote/nextcloud/:account/*path 200 201 This route can be used to put a file or directory in the NextCloud trash. 202 203 The `:account` parameter is the identifier of the NextCloud `io.cozy.account`. 204 205 The `*path` parameter is the path of the file/directory on the NextCloud. 206 207 **Note:** a permission on `DELETE io.cozy.files` is required to use this route. 208 209 ### Request 210 211 ```http 212 DELETE /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/Documents/Images/Clouds HTTP/1.1 213 Host: cozy.example.net 214 Authorization: Bearer eyJhbG... 215 ``` 216 217 ### Response 218 219 ```http 220 HTTP/1.1 204 No Content 221 ``` 222 223 #### Status codes 224 225 - 204 No Content, when the file/directory has been put in the trash 226 - 400 Bad Request, when the account is not configured for NextCloud, or the `To` parameter is missing 227 - 401 Unauthorized, when authentication to the NextCloud fails 228 - 404 Not Found, when the account is not found or the file/directory is not found on the NextCloud 229 230 ## POST /remote/nextcloud/:account/move/*path 231 232 This route can be used to move or rename a file/directory on the NextCloud. 233 The new path must be given with the `To` parameter in the query-string. 234 235 The `:account` parameter is the identifier of the NextCloud `io.cozy.account`. 236 237 The `*path` parameter is the path of the file on the NextCloud. 238 239 **Note:** a permission on `POST io.cozy.files` is required to use this route. 240 241 ### Request 242 243 ```http 244 POST /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/move/Documents/wallpaper.jpg?To=/Wallpaper.jpg HTTP/1.1 245 Host: cozy.example.net 246 Authorization: Bearer eyJhbG... 247 ``` 248 249 ### Response 250 251 ```http 252 HTTP/1.1 204 No Content 253 ``` 254 255 #### Status codes 256 257 - 204 No Content, when the file/directory has been moved 258 - 400 Bad Request, when the account is not configured for NextCloud 259 - 401 Unauthorized, when authentication to the NextCloud fails 260 - 404 Not Found, when the account is not found or the file/directory is not found on the NextCloud 261 - 409 Conflict, when a file already exists with the new name on the NextCloud. 262 263 ## POST /remote/nextcloud/:account/copy/*path 264 265 This route can be used to create a copy of a file in the same directory, with a 266 copy suffix in its name. The new name can be optionaly given with the `Name` 267 parameter in the query-string. 268 269 The `:account` parameter is the identifier of the NextCloud `io.cozy.account`. 270 271 The `*path` parameter is the path of the file on the NextCloud. 272 273 **Note:** a permission on `POST io.cozy.files` is required to use this route. 274 275 ### Request 276 277 ```http 278 POST /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/copy/Documents/wallpaper.jpg HTTP/1.1 279 Host: cozy.example.net 280 Authorization: Bearer eyJhbG... 281 ``` 282 283 ### Response 284 285 ```http 286 HTTP/1.1 201 Created 287 Content-Type: application/json 288 ``` 289 290 ```json 291 { 292 "ok": true 293 } 294 ``` 295 296 #### Status codes 297 298 - 201 Created, when the file has been copied 299 - 400 Bad Request, when the account is not configured for NextCloud 300 - 401 Unauthorized, when authentication to the NextCloud fails 301 - 404 Not Found, when the account is not found or the file/directory is not found on the NextCloud 302 - 409 Conflict, when a file already exists with the new name on the NextCloud. 303 304 ## POST /remote/nextcloud/:account/downstream/*path 305 306 This route can be used to move a file from the NextCloud to the Cozy. 307 308 The `:account` parameter is the identifier of the NextCloud `io.cozy.account`. 309 310 The `*path` parameter is the path of the file on the NextCloud. 311 312 The `To` parameter in the query-string must be given, as the ID of the 313 directory on the Cozy where the file will be put. 314 315 **Note:** a permission on `POST io.cozy.files` is required to use this route. 316 317 ### Request 318 319 ```http 320 POST /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/downstream/Documents/Images/sunset.jpg?To=b3ecbc00f4ba013c2bf418c04daba326 HTTP/1.1 321 Host: cozy.example.net 322 Authorization: Bearer eyJhbG... 323 ``` 324 325 ### Response 326 327 ```http 328 HTTP/1.1 201 Created 329 Content-Type: application/vnd.api+json 330 ``` 331 332 ```json 333 { 334 "data": { 335 "type": "io.cozy.files", 336 "id": "7b41fb7c31e87eeaf13a54bc32001830", 337 "attributes": { 338 "type": "file", 339 "name": "sunset.jpg", 340 "dir_id": "b3ecbc00f4ba013c2bf418c04daba326", 341 "created_at": "2024-05-15T09:24:39.460655706+02:00", 342 "updated_at": "2024-05-15T09:24:39.460655706+02:00", 343 "size": "54321", 344 "md5sum": "1B2M2Y8AsgTpgAmY7PhCfg==", 345 "mime": "image/jpeg", 346 "class": "image", 347 "executable": false, 348 "trashed": false, 349 "encrypted": false, 350 "cozyMetadata": { 351 "doctypeVersion": "1", 352 "metadataVersion": 1, 353 "createdAt": "2024-05-15T09:24:38.971901347+02:00", 354 "updatedAt": "2024-05-15T09:24:38.971901347+02:00", 355 "createdOn": "https://cozy.example.net/", 356 "uploadedAt": "2024-05-15T09:24:38.971901347+02:00", 357 "uploadedOn": "https://cozy.example.net/" 358 } 359 }, 360 "meta": { 361 "rev": "1-cfed435c4ad72b911b31ed775e3024df" 362 }, 363 "links": { 364 "self": "/files/7b41fb7c31e87eeaf13a54bc32001830" 365 }, 366 "relationships": { 367 "parent": { 368 "links": { 369 "related": "/files/b3ecbc00f4ba013c2bf418c04daba326" 370 }, 371 "data": { 372 "id": "b3ecbc00f4ba013c2bf418c04daba326", 373 "type": "io.cozy.files" 374 } 375 }, 376 "referenced_by": { 377 "links": { 378 "self": "/files/7b41fb7c31e87eeaf13a54bc32001830/relationships/references" 379 } 380 } 381 } 382 } 383 } 384 ``` 385 386 #### Status codes 387 388 - 201 Created, when the file has been moved from the NextCloud to the Cozy 389 - 400 Bad Request, when the account is not configured for NextCloud 390 - 401 Unauthorized, when authentication to the NextCloud fails 391 - 404 Not Found, when the account is not found or the file is not found on the NextCloud 392 393 ## POST /remote/nextcloud/:account/upstream/*path 394 395 This route can be used to move a file from the Cozy to the NextCloud. 396 397 The `:account` parameter is the identifier of the NextCloud `io.cozy.account`. 398 399 The `*path` parameter is the path of the file on the NextCloud. 400 401 The `From` parameter in the query-string must be given, as the ID of the 402 file on the Cozy that will be moved. 403 404 **Note:** a permission on `POST io.cozy.files` is required to use this route. 405 406 ### Request 407 408 ```http 409 POST /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/upstream/Documents/Images/sunset2.jpg?From=7b41fb7c31e87eeaf13a54bc32001830 HTTP/1.1 410 Host: cozy.example.net 411 Authorization: Bearer eyJhbG... 412 ``` 413 414 ### Response 415 416 ```http 417 HTTP/1.1 204 No Content 418 ``` 419 420 #### Status codes 421 422 - 204 No Content, when the file has been moved from the Cozy to the NextCloud 423 - 400 Bad Request, when the account is not configured for NextCloud 424 - 401 Unauthorized, when authentication to the NextCloud fails 425 - 404 Not Found, when the account is not found or the file is not found on the Cozy