Table of contents

Konnectors

It is possible to manage konnectors applications from the stack. The source-code of the konnector is installed on the cozy and the user can manage its execution via our job system and the konnector worker.

Install a konnector

The manifest

An exhaustive manifest specification is available in the Cozy Apps Registry documentation

POST /konnectors/:slug

Install a konnector, ie download the files and put them in /konnectors/:slug in the virtual file system of the user, create an io.cozy.konnectors document, register the permissions, etc.

This endpoint is asynchronous and returns a successful return as soon as the konnector installation has started, meaning we have successfully reached the manifest and started to fetch konnector source code.

To make this endpoint synchronous, use the header Accept: text/event-stream. This will make a eventsource stream sending the manifest and returning when the konnector has been installed or failed.

Status codes

Query-String

Parameter Description
Source URL from where the app can be downloaded (only for install)

Request

POST /konnectors/bank101?Source=git://github.com/cozy/cozy-bank101.git HTTP/1.1
Accept: application/vnd.api+json

Response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.api+json
{
  "data": [{
    "id": "4cfbd8be-8968-11e6-9708-ef55b7c20863",
    "type": "io.cozy.konnectors",
    "meta": {
      "rev": "1-7a1f918147df94580c92b47275e4604a"
    },
    "attributes": {
      "name": "bank101",
      "state": "installing",
      "slug": "bank101",
      ...
    },
    "links": {
      "self": "/konnectors/bank101"
    }
  }]
}

Note: it’s possible to choose a git branch by passing it in the fragment like this:

POST /konnectors/bank101-dev?Source=git://github.com/cozy/cozy-bank101.git%23dev HTTP/1.1

PUT /konnectors/:slug

Update a konnector source code with the specified slug name.

This endpoint is asynchronous and returns a successful return as soon as the konnector installation has started, meaning we have successfully reached the manifest and started to fetch konnector source code.

To make this endpoint synchronous, use the header Accept: text/event-stream. This will make a eventsource stream sending the manifest and returning when the konnector has been updated or failed.

Request

PUT /konnectors/bank101 HTTP/1.1
Accept: application/vnd.api+json

Response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.api+json
{
  "data": [{
    "id": "4cfbd8be-8968-11e6-9708-ef55b7c20863",
    "type": "io.cozy.konnectors",
    "meta": {
      "rev": "1-7a1f918147df94580c92b47275e4604a"
    },
    "attributes": {
      "name": "bank101",
      "state": "installing",
      "slug": "bank101",
      ...
    },
    "links": {
      "self": "/konnectors/bank101"
    }
  }]
}

Status codes

Advanced usage

Two optional query parameters are available for a konnector update: - PermissionsAcked: (defaults to true) - Tells that the user accepted the permissions/ToS. It is useful if there are newer permissions or Terms Of Service and you want to be sure they were read or accepted. If set to false, the update will be blocked and the user will be told that a new konnector version is available

Examples:

You can combine these parameters to use a precise konnector version and stay on another channel (when permissions are different): - Install a version (e.g. 1.0.0). - Ask an update to stable channel with PermissionsAcked to false - Source will be stable, and your version remains 1.0.0

List installed konnectors

GET /konnectors/

Request

GET /konnectors/ HTTP/1.1
Accept: application/vnd.api+json

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
  "data": [{
    "id": "4cfbd8be-8968-11e6-9708-ef55b7c20863",
    "type": "io.cozy.konnectors",
    "meta": {
      "rev": "1-7a1f918147df94580c92b47275e4604a"
    },
    "attributes": {
      "name": "bank101",
      "state": "installing",
      "slug": "bank101",
      ...
    },
    "links": {
      "self": "/konnectors/bank101"
    }
  }]
}

Get informations about a konnector

GET /konnectors/:slug

Uninstall a konnector

DELETE /apps/:slug

Request

DELETE /konnectors/bank101 HTTP/1.1

Response

HTTP/1.1 204 No Content