Apps registry

The apps registry is a place where developers can submit their applications, both web apps and konnectors. The applications metadata are stored and versioned. It can be used by a cozy to list applications to be installed, and for auto-updating the applications.

We define the applications registry as an API. This should allow us to defer the real implementation of the registry storage and allow different store implementations.

The stack itself implement the querying part of the registry API, proxying the request to the registries attached to the instance.

Publishing on our official registries

In order for you to publish on our official registries, please follow this howto describing how to obtain a token and parameter you repository to automatically publish versions.

Channels

We differentiate three channels of release for each application:

For each of these channels, the version string has a different format which differentiate the version channel:

Version order

TLDR: 1.0.0-dev. < 1.0.0 and 1.0.0-beta. < 1.0.0, make sure you upgrade your app version after publishing stable.

The order used to determine the latest version of a channel is the following:

- `1.0.0-dev.*  < 1.0.0 (dev < stable)`
- `1.0.0-beta.* < 1.0.0 (beta < stable)`
- `1.0.0-beta.1 < 1.0.0-beta.2`

To order beta and dev releases, we apply a sort by their creation date.

Objects

Two types of objects are managed in the registry: applications and versions.

Application

An application described a specific package. It is linked to multiple versions (releases) of the application.

An application object is mutable.

An application object contains the following fields:

Example:

{
  "slug": "drive",
  "type": "webapp",
  "editor": "cozy",
  "name": {
    "en": "Drive",
    "fr": "Drive"
  },
  "description": {
    "en": "The drive application",
    "fr": "L'application drive gestionnaire de fichier"
  },
  "category": "main",
  "repository": "https://github.com/cozy/cozy-drive",
  "locales": ["en", "fr"],
  "tags": ["foo", "bar", "baz"],
  "screenshots": ["screen1.jpg", "screen2.jpg"],
  "versions": {
    "stable": ["3.1.1"],
    "beta": ["3.1.1-beta.1"],
    "dev": ["3.1.1-dev.7a8354f74b50d7beead7719252a18ed45f55d070"]
  }
}

Version

A version object describe a specific release of an application.

A version object is immutable.

An application version object contains the following fields:

The version string should follow the channels rule.

Example:

{
  "slug": "drive",
  "type": "webapp",
  "version": "3.1.2",
  "created_at": "2017-07-05T07:54:40.982Z",
  "url": "http://.../3.1.2",
  "size": "1000",
  "sha256": "466aa0815926fdbf33fda523af2b9bf34520906ffbb9bf512ddf20df2992a46f",
  "manifest": {
    /* ... */
  }
}

APIs: Adding to registry

These APIs can be used to add elements to the registry.

POST /registry/:app

This route adds or modify an application to the registry. The content of the request should be a json object of an application.

Status codes

Request

POST /registry/drive HTTP/1.1
Authorization: Token AbCdE
{
  "slug": "drive",
  "editor": "cozy",
  "name": {
    "en": "Drive",
    "fr": "Drive"
  },
  "description": {
    "en": "The drive application"
  },
  "repository": "https://github.com/cozy/cozy-drive",
  "tags": ["foo", "bar", "baz"]
}

POST /registry/:app/:version or POST /registry/:app/versions

This route adds a version of an application to the registry to the specified channel (stable, beta or dev).

The content of the manifest file extracted from the application data is used to fill the fields of the version. Before adding the application version to the registry, the registry should check the following:

Fields of the object sent to this request:

Status codes

Request

Request to add a stable release:

POST /registry/drive/3.1.2 HTTP/1.1
Authorization: Token AbCdE
{
  "version": "3.1.2",
  "url": "https://github.com/cozy/cozy-drive/archive/v3.1.2.tar.gz",
  "sha256": "466aa0815926fdbf33fda523af2b9bf34520906ffbb9bf512ddf20df2992a46f"
}

Request to add a development release:

POST /registry/drive/3.1.2-dev.7a1618dff78ba445650f266bbe334cbc9176f03a HTTP/1.1
Authorization: Token AbCdE
{
  "version": "3.1.2-dev.7a1618dff78ba445650f266bbe334cbc9176f03a",
  "url":
    "https://github.com/cozy/cozy-photos-v3/archive/7a1618dff78ba445650f266bbe334cbc9176f03a.zip",
  "sha256": "466aa0815926fdbf33fda523af2b9bf34520906ffbb9bf512ddf20df2992a46f"
}

Request to add a version with optional parameters:

POST /registry/drive/3.1.2 HTTP/1.1
Authorization: Token AbCdE
{
  "version": "3.1.2",
  "url":
    "https://github.com/cozy/cozy-photos-v3/archive/7a1618dff78ba445650f266bbe334cbc9176f03a.zip",
  "sha256": "466aa0815926fdbf33fda523af2b9bf34520906ffbb9bf512ddf20df2992a46f",
  "parameters": { "foo": "bar", "baz": 123 }
}

Response

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://.../3.1.2
{
  "slug": "drive",
  "type": "webapp",
  "version": "3.1.2-dev.7a1618dff78ba445650f266bbe334cbc9176f03a",
  "created_at": "2017-07-05T07:54:40.982Z",
  "url": "http://.../7a1618dff78ba445650f266bbe334cbc9176f03a.zip",
  "size": "1000",
  "sha256": "466aa0815926fdbf33fda523af2b9bf34520906ffbb9bf512ddf20df2992a46f",
  "manifest": {
    /* ... */
  }
}

APIs: Querying registry

These routes define the querying part of a registry to access to the available applications and versions. These APIs are also implemented directly by the cozy-stack.

GET /registry

Get the list of all applications.

A pagination scheme is available via the limit and cursor query parameter. The filter[???] query parameters can be used to filter by fields values.

Filtering is allowed on the following fields:

Filtering is allowed on multiple tags with the , separator. For example: filter[tags]=foo,bar will match the applications with both foo and bar as tags.

Sorting is allowed on the following fields:

Query-String

Parameter Description
cursor the cursor of the last application on the previous page
limit the maximum number of applications to show
filter[] a filter to apply on fields of the application
sort name of the field on which to apply the sort of the list

Request

GET /registry?filter[category]=main&limit=20&sort=slug HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data": [
    {
      "slug": "drive",
      "type": "webapp",
      "editor": "cozy",
      "category": "main",
      "description": "The drive application",
      "versions": {
        "stable": ["3.1.1"],
        "beta": ["3.1.1-beta.1"],
        "dev": ["3.1.1-dev.7a8354f74b50d7beead7719252a18ed45f55d070"]
      },
      "repository": "https://github.com/cozy/cozy-drive",
      "license": "BSD"
    },
    {
      // ...
    }
  ],
  "meta": {
    "count": 2,
    "next_cursor": "..."
  }
}

GET /registry/:app

Get an application object by slug.

Request

GET /registry/drive HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "slug": "drive",
  "editor": "cozy",
  "description": "The drive application",
  "repository": "https://github.com/cozy/cozy-drive",
  "tags": ["foo", "bar", "baz"],
  "versions": {
    "stable": ["3.1.1"],
    "beta": ["3.1.1-beta.1"],
    "dev": ["3.1.1-dev.7a8354f74b50d7beead7719252a18ed45f55d070"]
  }
}

GET /registry/:app/icon

Get the current application icon.

Request

GET /registry/drive/icon HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: image/svg+xml

<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64">
  <g fill="none" fill-rule="evenodd"></g>
</svg>

GET /registry/:app/screenshots/:filename

Get the screenshot with the specified filename from the field screenshots of the application.

Request

GET /registry/drive/screenshots/screen1.jpg HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg

...

GET /registry/:app/:version

Get an application version.

Request

GET /registry/drive/3.1.1 HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "slug": "drive",
  "type": "webapp",
  "version": "3.1.1",
  "url": "http://.../3.1.1",
  "sha256": "466aa0815926fdbf33fda523af2b9bf34520906ffbb9bf512ddf20df2992a46f",
  "size": "1000",
  "created_at": "2017-07-05T07:54:40.982Z",
  "manifest": {
    /* ... */
  }
}

GET /registry/:app/:channel/latest

Get the latest version available on the specified channel.

Request

GET /registry/drive/dev/latest HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "slug": "drive",
  "type": "webapp",
  "version": "3.1.1",
  "url": "http://.../3.1.1",
  "sha256": "466aa0815926fdbf33fda523af2b9bf34520906ffbb9bf512ddf20df2992a46f",
  "size": "1000",
  "created_at": "2017-07-05T07:54:40.982Z",
  "manifest": {
    /* ... */
  }
}

Attaching a cozy-stack to a registry or a list of registries

In the configuration file of a stack, a registries namespace is added. This namespace can contain a list of URL for the different registries attached to the stack.

The stack itself implements the querying API of a registry. When querying this API, to ask for an application, the stack uses this hierarchy of registries to proxy or redirect the user.

The hierarchy can also be contextualised to specify different registries to different contexts. The default context is applied lastly.

Examples:

registries:
  - https://myregistry.home/
  - https://main.registry.cozy.io/
# In this example, a "context1" instance will have the equivalent of the
# following list of registries:
#
#   - https://context1.registry.cozy.io/
#   - https://myregistry.home/
#   - https://registry.cozy.io/
#

registries:
  context1:
    - https://context1.registry.cozy.io/

  context2:
    - https://context2.registry.cozy.io/

  default:
    - https://myregistry.home/
    - https://registry.cozy.io/

Authentication

The authentication is based on a token that allow you to publish applications and versions with for one specific editor name. This token is base64 encoded.

In order to receive this token, please take a look at the page on publication on the registry.