A Cozy's user can ask at any time to export a snapshot of all its data and metadata. This export takes place asynchronously and is separated in two parts:
- a metadata tarball containing the in a JSON format all the doctypes
- multi-part files tarballs containing the files (or a subpart of the files).
The export process is part of a worker described in the workers section of the documentation.
Endpoints described in this documentation require a permission on the
io.cozy.exports
doctype.
This endpoint can be used to create a new export job.
Exports options fields are:
parts_size
(optional) (int): the size in bytes of a tarball files part.max_age
(optional) (duration / nanosecs): the maximum age of the export data.with_doctypes
(optional) (string array): the list of exported doctypes
POST /move/exports HTTP/1.1
Host: source.cozy.localhost
Authorization: Bearer ...
Content-Type: application/vnd.api+json
{
"data": {
"attributes": {
"parts_size": 10240,
"with_doctypes": []
}
}
}
This endpoint can be used to fetch the metadata of an export.
Exports fields are:
parts_size
(int): the size in bytes of a tarball files part.parts_cursors
(string array): the list of cursors to access to the different files parts.with_doctypes
(string array): the list of exported doctypes (if empty of null, all doctypes are exported)state
(string): the state of the export ("exporting"
/"done"
/"error"
).created_at
(string / time): the date of creation of the exportexpires_at
(string / time): the date of expiration of the exporttotal_size
(int): the total size of the exported documents from CouchDBcreation_duration
(int): the amount of nanoseconds taken for the creation of the exporterror
(string): an error string if the export is in an"error"
state
GET /move/exports/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX HTTP/1.1
Host: source.cozy.localhost
Authorization: Bearer ...
Content-Type: application/vnd.api+json
{
"data": {
"type": "io.cozy.exports",
"id": "86dbb546ca49f0ed1ce0a1ff0d1b15e3",
"meta": {
"rev": "2-XXX"
},
"attributes": {
"parts_size": 10240,
"parts_cursors": ["AAA", "BBB", "CCC"],
"with_doctypes": [],
"state": "done",
"created_at": "2018-05-04T08:59:37.530693972+02:00",
"expires_at": "2018-05-11T08:59:37.530693972+02:00",
"total_size": 1123,
"creation_duration": 62978511,
"error": ""
}
}
}
This endpoint will download an archive containing the metadata and files of the
user, as part of a multi-part download. The cursor given should be one of the
defined in the export document parts_cursors
.
Only the first part of the archive contains the metadata.
To get all the parts, this endpoint must be called one time with no cursor, and
one time for each cursor in parts_cursors
.
This endpoint can be use to check that an export can be imported from the given URL, before doing the real import. It is called from the settings application, not from the cozy-move wizard.
POST /move/imports/precheck HTTP/1.1
Host: destination.cozy.localhost
Authorization: Bearer ...
Content-Type: application/vnd.api+json
{
"data": {
"attributes": {
"url": "https://settings.source.cozy.localhost/#/exports/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
}
}
204 No Content
if every thing is fine412 Precondition Failed
if no archive can be found at the given URL422 Entity Too Large
if the quota is too small to import the files
This endpoint can be used to really start an import.
POST /move/imports HTTP/1.1
Host: destination.cozy.localhost
Authorization: Bearer ...
Content-Type: application/vnd.api+json
{
"data": {
"attributes": {
"url": "https://settings.source.cozy.localhost/#/exports/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
}
}
HTTP/1.1 303 See Other
Location: https://destination.cozy.localhost/move/importing
This endpoint is called on the target Cozy by the source Cozy to block the
instance during the move. A source
parameter can be put in the query-string,
with the domain of the Cozy source (for information).
This shows a page for the user to wait that the import finishes.
This is a websocket endpoint that can be used to wait for the end of the import. The server will send an event when it is done (or errored):
server> {"redirect": "https://cozy.localhost:8080/auth/login"}
This endpoint is used by cozy-move to select the cozy source. If the user is already logged in, we don't ask its password again, as the delivered token will still need a confirmation by mail to start moving the Cozy.
GET /move/authorize?state=8d560d60&redirect_uri=https://move.cozycloud.cc/callback/source HTTP/1.1
Server: source.cozy.localhost
HTTP/1.1 302 Found
Location: https://move.cozycloud.cc/callback/source?code=543d7eb8149c&used=123456"a=5000000&state=8d560d60&vault=false
This endpoint is used by the settings application to open the move wizard.
POST /move/initialize HTTP/1.1
Host: source.cozy.localhost
HTTP/1.1 307 Temporary Redirect
Location: https://move.cozycloud.cc/initialize?code=834d7eb8149c&cozy_url=https://source.cozy.localhost&used=123456"a=5000000&client_id=09136b00-1778-0139-f0a7-543d7eb8149c&client_secret=NDkyZTEzMDA&vault=false
This endpoint is used after the user has selected both instances on cozy-move to prepare the export and send the confirmation mail.
POST /move/request HTTP/1.1
Content-Type: application/x-www-form-urlencoded
code=834d7eb8149c
&target_url=https://target.cozy.localhost/
&target_token=M2EwYjlhZjAtMTc3OC0wMTM5LWYwYWMtNTQzZDdlYjgxNDlj
&target_client_id=09136b00-1778-0139-f0a7-543d7eb8149c
&target_client_secret=NDkyZTEzMDA
Note: instead of code
, we can have token
, client_id
, and
client_secret
(depending if the user has started the workflow from the
settings app or from cozy-move).
HTTP/1.1 200 OK
Content-Type: application/html
This endpoint is used to confirm the move. It will ask the other Cozy to block its-self during the move and pushs a job for the export.
GET /move/go?secret=tNTQzZDdlYjgxNDlj HTTP/1.1
Host: source.cozy.localhost
HTTP/1.1 303 See Other
Location: https://target.cozy.localhost/move/importing
When the move has finished successfully, the target Cozy calls this endpoint on the source Cozy so that it can stop the konnectors and unblock the instance.
POST /move/finalize?subdomain=flat HTTP/1.1
Host: source.cozy.localhost
HTTP/1.1 204 No Content
If the export or the import fails during a move, the stack will call this endpoint for the other instance to unblock it.
POST /move/abort HTTP/1.1
Host: source.cozy.localhost
HTTP/1.1 204 No Content
This shows a page for the user with instructions about how to import their vault.