DE EN EN (Google)

Get exports

GET /api/v1/export?token=<token>

Retrieves an overview of all exports owned by the user.

Query String

token Session token acquired with /api/v1/session
limit maximum number of returned exports (optional, integer, 1000 if unset, maximum: 1000)
offset offset of first export to be returned (optional, integer, 0 if unset)
filter Comma-separated, disjunctive list of multiple filters.
Each filter may contain a type and/or a status filter part, multiple parts are separated by + and used in conjunction.
Each part consists of the filter variable name (either type or status) and its value(s), separated by :
Multiple values may be specified, separated by |
Example: filter=type:download+status:failed,type:export_incremental. Note, that + has to be URL-encoded (%2B) when used in query string.

Output

Object containing the following fields:

Name Description
limit requested maximum number of returned exports, null if not requested in URL
offset offset of first export to be returned, 0 if not requested in URL
count total number of exports found, ignoring limit
objects array of exports. The exports do not include _files, _downloads, _schedules _transports and _log.

Permissions

The session must be authenticated. A user can only manage its own exports.

HTTP status codes

200 Success
400 API error: something is malformed
403 Not Authenticated: session is not authenticated
500 Server error: internal server error
GET /api/v1/export/<export-id>?token=<token>

Retrieves a specific export.

Path parameters

export-id Export ID (integer)

Query String

token Session token acquired with /api/v1/session

Output

An export.

Permissions

The session must be authenticated. A user can only manage its own exports.

HTTP status codes

200 Success
400 API error: something is malformed
403 Not Authenticated: session is not authenticated
404 Not Found: export export_id not found
500 Server error: internal server error

Create an export

PUT /api/v1/export?token=<token>

Create a new export.

TODO: a secret passkey to access an Export’s downloadable files, is generated and stored for the new Export.

Query String

token Session token acquired with /api/v1/session

Input

An export.

Output

The created export.

Permissions

The session must be authenticated.

HTTP status codes

200 Success
400 API error: something is malformed
403 Not Authenticated: session is not authenticated
500 Server error: internal server error

Update an export

POST /api/v1/export/<export-id>?token=<token>

Update an export. POST only updates fields that are set, leaving the rest as they currently are.

TODO: if an update happens to an Export which is not in done or new state, the currently active Export is purged. After an update the Export gets again the new state.

Path parameters

export-id Export ID (integer)

Query String

token Session token acquired with /api/v1/session

Input

An export.

If the export is scheduled (there are one or more _schedules), it requires an explicitly set name.

Output

The updated export.

Permissions

The session must be authenticated. A user can only manage its own exports.

HTTP status codes

200 Success
400 API error: something is malformed
403 Not Authenticated: session is not authenticated
400 Export Name Required: export requires a name
404 Not Found: export export_id not found
500 Server error: internal server error

Delete an export

DELETE /api/v1/export/<export-id>?token=<token>

Delete export export-id.

Path parameters

export-id Export ID (integer)

Query String

token Session token acquired with /api/v1/session

Permissions

The session must be authenticated. A user can only manage its own exports.

HTTP status codes

200 Success
400 API error: something is malformed
403 Not Authenticated: session is not authenticated
404 Not Found: export export_id not found
500 Server error: internal server error

Get files from an Export

GET /api/v1/v1/export/<export-id>/file/<path>?token=<token>

The <path> can be retrieved from the _files Array returned in the Export. Clients can use this to build an Export browser. <path> needs to be a file.

Query String

token Session token acquired with /api/v1/session
disposition If set, a Content-Disposition header is set in response. Valid values: inline, attachment
filename If set, an alternative name for the downloaded file is used. The file extension is added automatically.

HTTP status codes

200 Success
302 Client is redirected to show an error page (using scheme /#server_error:<localization key>. This is only done if disposition parameter is set.
400 API error: something is malformed

Get files zipped from an Export

GET /api/v1/v1/export/<export-id>/zip/<path>?token=<token>

The <path> can be retrieved from the _files Array returned in the Export. The ZIP format is ZIP64, if ZIP32 is required a transport has to be used. Single files or directories can be zipped. With no path given, the full export is zipped.

The server generates the ZIP file on-thy-fly, so there is no Content-Length HTTP-Header set in the response.

token Session token acquired with /api/v1/session
disposition If set, a Content-Disposition header is set in response. Valid values: inline, attachment
filename If set, an alternative name for the downloaded ZIP file is used. Defaults to export name and (if a path other than "/" is provided) the leaf path name with a ".zip" suffix. The file extension (always ".zip") is added automatically.

HTTP status codes

200 Success
302 Client is redirected to show an error page (using scheme /#server_error:<localization key>. This is only done if disposition parameter is set.
400 API error: something is malformed

Download files from an Export

Each export generates a list of files to download the Export from. The ZIP files and TAR file is available through an anonymous access using a secret-passkey which is uniquely generated for each Export upon PUT.

Get a downloadable files from an Export

GET /api/v1/v1/export/<export-id>/download/<secret-passkey>/<name-of-export>[.<1-n>].zip>
GET /api/v1/v1/export/<export-id>/download/<secret-passkey>/<name-of-export>.zip>
GET /api/v1/v1/export/<export-id>/download/<secret-passkey>/<name-of-export>.tar>

The URL can be retrieved from the _download Map returned in the Exports Transports List.

Only Exports in the done state can be downloaded.

The URL can be retrieved from the _download Map returned in the Exports Transports List.

The URL for a downloadable file will be persistent over the lifetime of an export.

token Session token acquired with /api/v1/session
disposition If set, a Content-Disposition header is set in response. Valid values: inline, attachment
filename If set, an alternative name for the downloaded file is used. The file extension is added automatically.

Get with an invalid secret-passkey

If the secret-passkey used is invalid, the server uses a response with a “HTTP Location” redirect to redirect the Requester to a Frontend-URL to display a server error.

//#server_error:export.invalid.passkey

HTTP status codes

200 Success
302 Client is redirected to show an error page (using scheme /#server_error:<localization key>. This is only done if disposition parameter is set.
400 API error: something is malformed

Start an export

The export is queued to run immediately.

POST /api/v1/export/<export-id>/start?token=<token>

Path parameters

export-id Export ID (integer)

Query String

token Session token acquired with /api/v1/session

Permissions

The session must be authenticated. A user can only manage its own exports.

HTTP status codes

200 Success
400 API error: something is malformed
400 Already Running: the export requested to start is already running
403 Not Authenticated: session is not authenticated
404 Not Found: export export_id not found
500 Server error: internal server error

Stop an export

POST /api/v1/export/<export-id>/stop?token=<token>

Path parameters

export-id Export ID (integer)

Query String

token Session token acquired with /api/v1/session

Permissions

The session must be authenticated. A user can only manage its own exports.

HTTP status codes

200 Success
400 API error: something is malformed
403 Not Authenticated: session is not authenticated
404 Not Found: export export_id not found or not running
500 Server error: internal server error