

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¶

202 Accepted, when the konnector installation has been accepted.
400 Bad-Request, when the manifest of the konnector could not be processed (for instance, it is not valid JSON).
404 Not Found, when the manifest or the source of the konnector is not reachable.
422 Unprocessable Entity, when the sent data is invalid (for example, the slug is invalid or the Source parameter is not a proper or supported url)

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¶

202 Accepted, when the konnector installation has been accepted.
400 Bad-Request, when the manifest of the konnector could not be processed (for instance, it is not valid JSON).
404 Not Found, when the konnector with the specified slug was not found or when the manifest or the source of the konnector is not reachable.
422 Unprocessable Entity, when the sent data is invalid (for example, the slug is invalid or the Source parameter is not a proper or supported url)

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.\ > Note: PermissionsAcked can be skipped. \ If an instance is in a context configured with the parameter permissions_skip_verification sets to true, permissions verification will be ignored.

Source (defaults to source url installation):
- Use a different source to update this konnector (e.g. to install a beta or dev konnector version)

Examples:¶

You have a trainline konnector on a stable channel, and you want to update it to a particular beta version:

PUT /konnectors/trainline?Source=https://<konnectors-repository>/trainline/1.0.0-beta HTTP/1.1
Accept: application/vnd.api+json

You want to attempt the trainline konnector update, but prevent it if new permissions were added

PUT /konnectors/trainline?PermissionsAcked=false HTTP/1.1
Accept: application/vnd.api+json

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"
    }
  }],
  "links": {},
  "meta": {
    "count": 1
  }
}

This endpoint is paginated, default limit is currently 100. Two flags are available to retreieve the other konnectors if there are more than 100 konnectors installed: - limit - start_key: The first following doc ID of the next konnectors

The links object contains a ǹext generated-link for the next docs.

Request¶

GET /konnectors/?limit=50 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"
    }
  }, {...}],
  "links": {
    "next": "http://alice.example.com/konnectors/?limit=50&start_key=io.cozy.konnectors%2Ffookonnector"
  },
  "meta": {
    "count": 50
  }
}

Get informations about a konnector¶

GET /konnectors/:slug¶

This route is used to retrieve informations about a konnector installed on the cozy. By calling this route, the konnector will be updated synchronously.

Request¶

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

Response¶

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

{
  "data": {
    "type": "io.cozy.konnectors",
    "id": "io.cozy.konnectors/pajemploi",
    "attributes": {
      "name": "Pajemploi",
      "editor": "Cozy",
      "icon": "icon.svg",
      "type": "konnector",
      "language": "node",
      ...
    },
    "meta": {
      "rev": "8-1197cab1c9ecc89cef676567410cf7c5"
    },
    "links": {
      "self": "/konnectors/pajemploi",
      "icon": "/konnectors/pajemploi/icon/1.5.2",
      "permissions": "/permissions/konnectors/pajemploi"
    }
  }
}

Download the code of a konnector¶

This endpoint is used by the flagship app to download the code of a konnector, in order to install it on the user’s device.

GET /konnectors/:slug/download & GET /konnectors/:slug/download/:version¶

The first route will download a tarball of the source code of the latest installed version of the konnector. The second route will force a specific version of the konnector (and a 412 Precondition failed may be sent if the code of this specific version is not available).

Request¶

GET /konnectors/pajemploi/download/3.0.1 HTTP/1.1
Authorization: Bearer flagship-token
Host: cozy.example.net

Response¶

HTTP/1.1 200 OK
Content-Type: application/gzip

When the konnector has been installed from the registry, the stack will respond with a redirect to the registry. In that case, the downloaded tarball can be gzipped or not (the registry allows both). When the konnector is installed from another source, the stack will create a gzipped tarball and send it to the client.

Uninstall a konnector¶

DELETE /konnectors/:slug¶

Request¶

DELETE /konnectors/bank101 HTTP/1.1

Response¶

HTTP/1.1 204 No Content

Or, if the konnector has still some accounts configured:

HTTP/1.1 202 Accepted

In this case, the stack will accept the uninstall request, then it will clean the accounts (locally and remotely), and only after that, the konnector will be removed.

Add a trigger¶

POST /konnectors/:slug/trigger¶

This endpoint creates a @cron trigger for the given konnector. The manifest is used to generate the crontab.

Query-String¶

Parameter	Description
AccountID	The identifier of the io.cozy.accounts that will be used to run the konnector
ExecNow	`true` if you want to run a job just after the trigger creation

Request¶

POST /konnectors/pajemploi/trigger?AccountID=4eee63e069690139df83543d7eb8149c HTTP/1.1

Response¶

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

{
  "data": {
    "type": "io.cozy.triggers",
    "id": "8cfeef1069690139df84543d7eb8149c",
    "attributes": {
      "type": "@cron",
      "arguments": "0 9 3 * * 1",
      "worker": "konnector",
      "message": {
        "account": "4eee63e069690139df83543d7eb8149c",
        "konnector": "pajemploi"
      }
    },
    "links": {
      "self": "/jobs/triggers/8cfeef1069690139df84543d7eb8149c"
    }
  }
}

Send konnector logs to cozy-stack¶

POST /konnectors/:slug/logs¶

Send client-side logs to cozy-stack so they can be stored in the server’s logging system.

Status codes¶

204 No Content, when all the log lines have been processed.
400 Bad-Request, when the JSON body is invalid.
404 Not Found, when no konnectors with the given slug could be found.
422 Unprocessable Entity, when the sent data is invalid (for example, the slug is invalid or log level does not exist)

Request¶

POST /konnectors/pajemploi/logs HTTP/1.1
Accept: application/vnd.api+json

[
  { "timestamp": "2022-10-27T17:13:37.293Z", "level": "info", "msg": "Connecting to remote site..." },
  { "timestamp": "2022-10-27T17:13:38.382Z", "level": "error", "msg": "LOGIN_FAILED" }
]

Response¶

HTTP/1.1 204 No Content