github.com/cozy/cozy-stack@v0.0.0-20240327093429-939e4a21320e/docs/not-synchronized-vfs.md (about)

     1  [Table of contents](README.md#table-of-contents)
     2  
     3  # Not synchronized directories
     4  
     5  ## What we want?
     6  
     7  The directories in the Virtual File System can be ignored for synchronization
     8  purpose by some clients. For example, a user may want to not synchronize their
     9  `Videos` directory as it takes too much space for their laptop. Or they may want
    10  to not synchronize a directory with personal documents on the desktop owned by
    11  their employer. By default, all the directories are synchronized everywhere but
    12  it is possible to tell for each directory the devices where the directory won't
    13  be synchronized. The stack tracks this with a `not_synchronized_on` field on
    14  the directory documents.
    15  
    16  ### Example
    17  
    18  ```json
    19  {
    20    "data": {
    21      "type": "io.cozy.files",
    22      "id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee",
    23      "meta": {
    24        "rev": "1-ff3beeb456eb"
    25      },
    26      "attributes": {
    27        "type": "directory",
    28        "name": "phone",
    29        "path": "/Documents/phone",
    30        "created_at": "2016-09-19T12:35:08Z",
    31        "updated_at": "2016-09-19T12:35:08Z",
    32        "tags": ["bills", "konnectors"],
    33        "cozyMetadata": {
    34          "doctypeVersion": "1",
    35          "metadataVersion": 1,
    36          "createdAt": "2016-09-20T18:32:48Z",
    37          "createdByApp": "drive",
    38          "createdOn": "https://cozy.example.com/",
    39          "updatedAt": "2016-09-20T18:32:48Z"
    40        }
    41      },
    42      "relationships": {
    43        "parent": {
    44          "links": {
    45            "related": "/files/fce1a6c0-dfc5-11e5-8d1a-1f854d4aaf81"
    46          },
    47          "data": {
    48            "type": "io.cozy.files",
    49            "id": "fce1a6c0-dfc5-11e5-8d1a-1f854d4aaf81"
    50          }
    51        },
    52        "not_synchronized_on": {
    53          "links": {
    54            "self": "/files/6494e0ac-dfcb-11e5-88c1-472e84a9cbee/relationships/not_synchronized_on"
    55          },
    56          "data": [
    57            {
    58              "type": "io.cozy.oauth.clients",
    59              "id": "653dfdb0-0595-0139-92df-543d7eb8149c"
    60            }
    61          ]
    62        }
    63      },
    64      "links": {
    65        "self": "/files/6494e0ac-dfcb-11e5-88c1-472e84a9cbee"
    66      }
    67    }
    68  }
    69  ```
    70  
    71  ## Routes
    72  
    73  ### POST /files/:dir-id/relationships/not_synchronized_on
    74  
    75  Ask to not synchronize a directory on one or several devices.
    76  
    77  #### Request
    78  
    79  ```http
    80  POST /files/6494e0ac-dfcb-11e5-88c1-472e84a9cbee/relationships/not_synchronized_on HTTP/1.1
    81  Content-Type: application/vnd.api+json
    82  Accept: application/vnd.api+json
    83  ```
    84  
    85  ```json
    86  {
    87      "data": [
    88          {
    89              "type": "io.cozy.oauth.clients",
    90              "id": "f9ef4dc0-0596-0139-92e0-543d7eb8149c"
    91          }
    92      ]
    93  }
    94  ```
    95  
    96  #### Response
    97  
    98  ```http
    99  HTTP/1.1 200 OK
   100  Content-Type: application/vnd.api+json
   101  ```
   102  
   103  ```json
   104  {
   105      "meta": {
   106          "rev": "3-485d439530110",
   107          "count": 2
   108      },
   109      "data": [
   110          {
   111              "type": "io.cozy.oauth.clients",
   112              "id": "653dfdb0-0595-0139-92df-543d7eb8149c"
   113          },
   114          {
   115              "type": "io.cozy.oauth.clients",
   116              "id": "f9ef4dc0-0596-0139-92e0-543d7eb8149c"
   117          }
   118      ]
   119  }
   120  ```
   121  
   122  ### DELETE /files/:file-id/relationships/not_synchronized_on
   123  
   124  Ask to synchronize again the directory on one or several devices.
   125  
   126  #### Request
   127  
   128  ```http
   129  DELETE /files/6494e0ac-dfcb-11e5-88c1-472e84a9cbee/relationships/not_synchronized_on HTTP/1.1
   130  Content-Type: application/vnd.api+json
   131  Accept: application/vnd.api+json
   132  ```
   133  
   134  ```json
   135  {
   136      "data": [
   137          {
   138              "type": "io.cozy.oauth.clients",
   139              "id": "f9ef4dc0-0596-0139-92e0-543d7eb8149c"
   140          }
   141      ]
   142  }
   143  ```
   144  
   145  #### Response
   146  
   147  ```http
   148  HTTP/1.1 200 OK
   149  Content-Type: application/vnd.api+json
   150  ```
   151  
   152  ```json
   153  {
   154      "meta": {
   155          "rev": "4-1f7ef1be3cb",
   156          "count": 1
   157      },
   158      "data": [
   159          {
   160              "type": "io.cozy.oauth.clients",
   161              "id": "653dfdb0-0595-0139-92df-543d7eb8149c"
   162          }
   163      ]
   164  }
   165  ```
   166  
   167  ### GET /data/:type/:doc-id/relationships/not_synchronizing
   168  
   169  Returns all the directory ids that are not synchronized on the given device.
   170  
   171  Contents is paginated following [jsonapi conventions](http-api.md#pagination).
   172  The default limit is 100 entries. The maximal number of entries per page is
   173  1000.
   174  
   175  It is possible to include the whole documents for the directories by adding
   176  `include=files` to the query string.
   177  
   178  #### Request
   179  
   180  ```http
   181  GET /data/io.cozy.oauth.clients/653dfdb0-0595-0139-92df-543d7eb8149c/relationships/not_synchronizing HTTP/1.1
   182  Content-Type: application/vnd.api+json
   183  Accept: application/vnd.api+json
   184  ```
   185  
   186  #### Response
   187  
   188  ```http
   189  HTTP/1.1 200 OK
   190  Content-Type: application/vnd.api+json
   191  ```
   192  
   193  ```json
   194  {
   195      "data": [
   196          {
   197              "type": "io.cozy.files",
   198              "id": "11400320-07b7-0139-4fe8-543d7eb8149c"
   199          },
   200          {
   201              "type": "io.cozy.files",
   202              "id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee"
   203          }
   204      ]
   205  }
   206  ```
   207  
   208  ### POST /data/:type/:doc-id/relationships/not_synchronizing
   209  
   210  When configuring a device, it's tedious to add the `not_synchronized_on` for
   211  each directory individually. This route allows to make it in bulk.
   212  
   213  #### Request
   214  
   215  ```http
   216  POST /data/io.cozy.oauth.clients/653dfdb0-0595-0139-92df-543d7eb8149c/relationships/not_synchronizing HTTP/1.1
   217  Content-Type: application/vnd.api+json
   218  Accept: application/vnd.api+json
   219  ```
   220  
   221  ```json
   222  {
   223      "data": [
   224          {
   225              "type": "io.cozy.files",
   226              "id": "38086350-07c0-0139-4fe9-543d7eb8149c"
   227          },
   228          {
   229              "type": "io.cozy.files",
   230              "id": "3d447470-07c0-0139-4fea-543d7eb8149c"
   231          }
   232      ]
   233  }
   234  ```
   235  
   236  #### Response
   237  
   238  ```http
   239  HTTP/1.1 204 No Content
   240  Content-Type: application/vnd.api+json
   241  ```
   242  
   243  **Note**: if one of the id is a file, the response will be a 400 Bad Request.
   244  References are only for directories.
   245  
   246  ### DELETE /data/:type/:doc-id/relationships/not_synchronizing
   247  
   248  This bulk deletion of not_synchronized_on on many directories can be useful
   249  when configuring a device.
   250  
   251  #### Request
   252  
   253  ```http
   254  DELETE /data/io.cozy.oauth.clients/653dfdb0-0595-0139-92df-543d7eb8149c/relationships/not_synchronizing HTTP/1.1
   255  Content-Type: application/vnd.api+json
   256  Accept: application/vnd.api+json
   257  ```
   258  
   259  ```json
   260  {
   261      "data": [
   262          {
   263              "type": "io.cozy.files",
   264              "id": "38086350-07c0-0139-4fe9-543d7eb8149c"
   265          },
   266          {
   267              "type": "io.cozy.files",
   268              "id": "3d447470-07c0-0139-4fea-543d7eb8149c"
   269          }
   270      ]
   271  }
   272  ```
   273  
   274  #### Response
   275  
   276  ```http
   277  HTTP/1.1 204 No Content
   278  Content-Type: application/vnd.api+json
   279  ```
   280  
   281  ## Usage
   282  
   283  When an OAuth client makes a request for the changes feed on the
   284  `io.cozy.files` doctype (via `/data/io.cozy.files/_changes`), the output will
   285  be filtered. If a directory or file is inside a directory with the
   286  `not_synchronized_on` attribute set on for this client, the document will be
   287  replaced by a fake entry with `_deleted: true`.