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