Proxy for a remote NextCloud¶

The nextcloud konnector can be used to create an io.cozy.account for a NextCloud. Then, the stack can be used as a client for this NextCloud account. Currently, it supports files operations via WebDAV.

GET /remote/nextcloud/:account/*path¶

This route can be used to list the files and subdirectories inside a directory of NextCloud.

With Dl=1 in the query-string, it can also be used to download a file.

The :account parameter is the identifier of the NextCloud io.cozy.account. It is available with the cozyMetadata.sourceAccount of the shortcut file for example.

The *path parameter is the path of the file/directory on the NextCloud.

Note: a permission on GET io.cozy.files is required to use this route.

Request (list)¶

GET /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/Documents HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Response (list)¶

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "type": "io.cozy.remote.nextcloud.files",
      "id": "192172",
      "attributes": {
        "type": "directory",
        "name": "Images",
        "path": "/Documents/Images",
        "updated_at": "Thu, 02 May 2024 09:29:53 GMT",
        "etag": "\"66335d11c4b91\""
      },
      "meta": {},
      "links": {
        "self": "https://nextcloud.example.net/apps/files/files/192172?dir=/Documents"
      }
    },
    {
      "type": "io.cozy.remote.nextcloud.files",
      "id": "208937",
      "attributes": {
        "type": "file",
        "name": "BugBounty.pdf",
        "path": "/Documents/BugBounty.pdf",
        "size": 2947,
        "mime": "application/pdf",
        "class": "pdf",
        "updated_at": "Mon, 14 Jan 2019 08:22:21 GMT",
        "etag": "\"dd1a602431671325b7c1538f829248d9\""
      },
      "meta": {},
      "links": {
        "self": "https://nextcloud.example.net/apps/files/files/208937?dir=/Documents"
      }
    },
    {
      "type": "io.cozy.remote.nextcloud.files",
      "id": "615827",
      "attributes": {
        "type": "directory",
        "name": "Music",
        "name": "/Documents/Music",
        "updated_at": "Thu, 02 May 2024 09:28:37 GMT",
        "etag": "\"66335cc55204b\""
      },
      "meta": {},
      "links": {
        "self": "https://nextcloud.example.net/apps/files/files/615827?dir=/Documents"
      }
    },
    {
      "type": "io.cozy.remote.nextcloud.files",
      "id": "615828",
      "attributes": {
        "type": "directory",
        "name": "Video",
        "path": "/Documents/Video",
        "updated_at": "Thu, 02 May 2024 09:29:53 GMT",
        "etag": "\"66335d11c2318\""
      },
      "meta": {},
      "links": {
        "self": "https://nextcloud.example.net/apps/files/files/615828?dir=/Documents"
      }
    }
  ],
  "meta": {
    "count": 5
  }
}

Request (download)¶

GET /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/Documents/Wallpaper.jpg?Dl=1 HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Response (download)¶

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 12345
Content-Disposition: attachment; filename="Wallpaper.jpg"

...

Status codes¶

200 OK, for a success
401 Unauthorized, when authentication to the NextCloud fails
404 Not Found, when the account is not found or the directory is not found on the NextCloud

PUT /remote/nextcloud/:account/*path¶

This route can be used to create a directory, or upload a file, on the NextCloud. The query-string parameter Type should be file when uploading a file.

The :account parameter is the identifier of the NextCloud io.cozy.account.

The *path parameter is the path of the file/directory on the NextCloud.

Note: a permission on POST io.cozy.files is required to use this route.

Request (directory)¶

PUT /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/Documents/Images/Clouds?Type=directory HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Response (directory)¶

HTTP/1.1 201 Created
Content-Type: application/json

{
  "ok": true
}

Request (file)¶

PUT /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/Documents/Images/sunset.jpg?Type=file HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...
Content-Type: image/jpeg
Content-Length: 54321

...

Response (file)¶

HTTP/1.1 201 Created
Content-Type: application/json

{
  "ok": true
}

Status codes¶

201 Created, when the directory has been created
400 Bad Request, when the account is not configured for NextCloud
401 Unauthorized, when authentication to the NextCloud fails
404 Not Found, when the account is not found or the parent directory is not found on the NextCloud
409 Conflict, when a directory or file already exists at this path on the NextCloud.

DELETE /remote/nextcloud/:account/*path¶

This route can be used to put a file or directory in the NextCloud trash.

The :account parameter is the identifier of the NextCloud io.cozy.account.

The *path parameter is the path of the file/directory on the NextCloud.

Note: a permission on DELETE io.cozy.files is required to use this route.

Request¶

DELETE /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/Documents/Images/Clouds HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Response¶

HTTP/1.1 204 No Content

Status codes¶

204 No Content, when the file/directory has been put in the trash
400 Bad Request, when the account is not configured for NextCloud, or the To parameter is missing
401 Unauthorized, when authentication to the NextCloud fails
404 Not Found, when the account is not found or the file/directory is not found on the NextCloud

POST /remote/nextcloud/:account/move/*path¶

This route can be used to move or rename a file/directory on the NextCloud. The new path must be given with the To parameter in the query-string.

The :account parameter is the identifier of the NextCloud io.cozy.account.

The *path parameter is the path of the file on the NextCloud.

Note: a permission on POST io.cozy.files is required to use this route.

Request¶

POST /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/move/Documents/wallpaper.jpg?To=/Wallpaper.jpg HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Response¶

HTTP/1.1 204 No Content

Status codes¶

204 No Content, when the file/directory has been moved
400 Bad Request, when the account is not configured for NextCloud
401 Unauthorized, when authentication to the NextCloud fails
404 Not Found, when the account is not found or the file/directory is not found on the NextCloud
409 Conflict, when a file already exists with the new name on the NextCloud.

POST /remote/nextcloud/:account/copy/*path¶

This route can be used to create a copy of a file in the same directory, with a copy suffix in its name. The new name can be optionaly given with the Name parameter in the query-string, or the full path can be given with Path parameter.

The :account parameter is the identifier of the NextCloud io.cozy.account.

The *path parameter is the path of the file on the NextCloud.

Note: a permission on POST io.cozy.files is required to use this route.

Request¶

POST /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/copy/Documents/wallpaper.jpg?Path=/Images/beach.jpg HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Response¶

HTTP/1.1 201 Created
Content-Type: application/json

{
  "ok": true
}

Status codes¶

201 Created, when the file has been copied
400 Bad Request, when the account is not configured for NextCloud
401 Unauthorized, when authentication to the NextCloud fails
404 Not Found, when the account is not found or the file/directory is not found on the NextCloud
409 Conflict, when a file already exists with the new name on the NextCloud.

POST /remote/nextcloud/:account/downstream/*path¶

This route can be used to move/copy a file from the NextCloud to the Cozy.

The :account parameter is the identifier of the NextCloud io.cozy.account.

The *path parameter is the path of the file on the NextCloud.

The To parameter in the query-string must be given, as the ID of the directory on the Cozy where the file will be put.

By default, the file will be moved, but using Copy=true in the query-string will makes a copy.

By default, if a file with the same name already exists in the destination directory, a new name will be automatically generated (e.g., “file (2).txt”). Using FailOnConflict=true in the query-string will make the route return a 409 Conflict error instead of auto-renaming the file.

Note: a permission on POST io.cozy.files is required to use this route.

Request¶

POST /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/downstream/Documents/Images/sunset.jpg?To=b3ecbc00f4ba013c2bf418c04daba326 HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Query parameters¶

To (required): The ID of the directory on the Cozy where the file will be put.
Copy (optional): Set to true to make a copy instead of moving the file. Default is false (move).
FailOnConflict (optional): Set to true to return a 409 Conflict error if a file with the same name already exists, instead of auto-renaming. Default is false (auto-rename).

Example with FailOnConflict¶

POST /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/downstream/Documents/Images/sunset.jpg?To=b3ecbc00f4ba013c2bf418c04daba326&FailOnConflict=true HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Response¶

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.files",
    "id": "7b41fb7c31e87eeaf13a54bc32001830",
    "attributes": {
      "type": "file",
      "name": "sunset.jpg",
      "dir_id": "b3ecbc00f4ba013c2bf418c04daba326",
      "created_at": "2024-05-15T09:24:39.460655706+02:00",
      "updated_at": "2024-05-15T09:24:39.460655706+02:00",
      "size": "54321",
      "md5sum": "1B2M2Y8AsgTpgAmY7PhCfg==",
      "mime": "image/jpeg",
      "class": "image",
      "executable": false,
      "trashed": false,
      "encrypted": false,
      "cozyMetadata": {
        "doctypeVersion": "1",
        "metadataVersion": 1,
        "createdAt": "2024-05-15T09:24:38.971901347+02:00",
        "updatedAt": "2024-05-15T09:24:38.971901347+02:00",
        "createdOn": "https://cozy.example.net/",
        "uploadedAt": "2024-05-15T09:24:38.971901347+02:00",
        "uploadedOn": "https://cozy.example.net/"
      }
    },
    "meta": {
      "rev": "1-cfed435c4ad72b911b31ed775e3024df"
    },
    "links": {
      "self": "/files/7b41fb7c31e87eeaf13a54bc32001830"
    },
    "relationships": {
      "parent": {
        "links": {
          "related": "/files/b3ecbc00f4ba013c2bf418c04daba326"
        },
        "data": {
          "id": "b3ecbc00f4ba013c2bf418c04daba326",
          "type": "io.cozy.files"
        }
      },
      "referenced_by": {
        "links": {
          "self": "/files/7b41fb7c31e87eeaf13a54bc32001830/relationships/references"
        }
      }
    }
  }
}

Status codes¶

201 Created, when the file has been moved from the NextCloud to the Cozy
400 Bad Request, when the account is not configured for NextCloud or the To parameter is missing
401 Unauthorized, when authentication to the NextCloud fails
404 Not Found, when the account is not found or the file is not found on the NextCloud
409 Conflict, when a file with the same name already exists in the destination directory and FailOnConflict=true is set

POST /remote/nextcloud/:account/upstream/*path¶

This route can be used to move/copy a file from the Cozy to the NextCloud.

The :account parameter is the identifier of the NextCloud io.cozy.account.

The *path parameter is the path of the file on the NextCloud.

The From parameter in the query-string must be given, as the ID of the file on the Cozy that will be moved.

By default, the file will be moved, but using Copy=true in the query-string will makes a copy.

Note: a permission on POST io.cozy.files is required to use this route.

Request¶

POST /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/upstream/Documents/Images/sunset2.jpg?From=7b41fb7c31e87eeaf13a54bc32001830 HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Response¶

HTTP/1.1 204 No Content

Status codes¶

204 No Content, when the file has been moved from the Cozy to the NextCloud
400 Bad Request, when the account is not configured for NextCloud
401 Unauthorized, when authentication to the NextCloud fails
404 Not Found, when the account is not found or the file is not found on the Cozy

GET /remote/nextcloud/:account/trash/*¶

This route can be used to list the files and directories inside the trashbin of NextCloud.

Request (list)¶

GET /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/trash/ HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Response (list)¶

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "type": "io.cozy.remote.nextcloud.files",
      "id": "613281",
      "attributes": {
        "type": "directory",
        "name": "Old",
        "path": "/trash/Old.d93571568",
        "updated_at": "Tue, 25 Jun 2024 14:31:44 GMT",
        "etag": "1719326384",
        "restore_path": "/Old"
      },
      "meta": {},
      "links": {
        "self": "https://nextcloud.example.net/apps/files/trashbin/613281?dir=/Old"
      }
    }
  ]
}

Status codes¶

200 OK, for a success
401 Unauthorized, when authentication to the NextCloud fails
404 Not Found, when the account is not found or the directory is not found on the NextCloud

POST /remote/nextcloud/:account/restore/*path¶

This route can be used to restore a file/directory from the trashbin on the NextCloud.

The :account parameter is the identifier of the NextCloud io.cozy.account.

The *path parameter is the path of the file on the NextCloud.

Note: a permission on POST io.cozy.files is required to use this route.

Request¶

POST /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/restore/trash/Old.d93571568 HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Response¶

HTTP/1.1 204 No Content

Status codes¶

204 No Content, when the file/directory has been restored
400 Bad Request, when the account is not configured for NextCloud
401 Unauthorized, when authentication to the NextCloud fails
404 Not Found, when the account is not found or the file/directory is not found on the NextCloud
409 Conflict, when a directory or file already exists where the file/directory should be restored on the NextCloud.

DELETE /remote/nextcloud/:account/trash/*¶

This route can be used to delete a file in the trash.

Request¶

DELETE /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/trash/document-v1.docx.d64283654 HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Response¶

HTTP/1.1 204 No Content

Status codes¶

204 No Content, when the file/directory has been put in the trash
400 Bad Request, when the account is not configured for NextCloud, or the To parameter is missing
401 Unauthorized, when authentication to the NextCloud fails
404 Not Found, when the account is not found or the file/directory is not found on the NextCloud

DELETE /remote/nextcloud/:account/trash¶

This route can be used to empty the trash bin on NextCloud.

Request¶

DELETE /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/trash HTTP/1.1
Host: cozy.example.net
Authorization: Bearer eyJhbG...

Response¶

HTTP/1.1 204 No Content