Table of contents

Data System

Typing

The notion of document type does not exist in Couchdb.

Cozy-stack introduce this notion through a special _type field.

This type name cannot contain /, and it should be unique among all developers, it is recommended to use the Java naming convention with a domain you own.

All CozyCloud types will be prefixed by io.cozy and be pluralized. Example : /data/io.cozy.events/6494e0ac-dfcb-11e5-88c1-472e84a9cbee Where, io.cozy. is the developer specific prefix, events the actual type, and 6494e0ac-dfcb-11e5-88c1-472e84a9cbee the document’s unique id .

Access a document

Request

GET /data/:type/:id HTTP/1.1
GET /data/io.cozy.events/6494e0ac-dfcb-11e5-88c1-472e84a9cbee HTTP/1.1

Response OK

HTTP/1.1 200 OK
Date: Mon, 27 Sept 2016 12:28:53 GMT
Content-Length: ...
Content-Type: application/json
Etag: "3-6494e0ac6494e0ac"
{
  "_id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee",
  "_type": "io.cozy.events",
  "_rev": "3-6494e0ac6494e0ac",
  "startdate": "20160823T150000Z",
  "enddate": "20160923T160000Z",
  "summary": "A long month",
  "description": "I could go on and on and on ...."
}

Response Error

HTTP/1.1 404 Not Found
Content-Length: ...
Content-Type: application/json
{
  "status": 404,
  "error": "not_found",
  "reason": "deleted",
  "title": "Event deleted",
  "details": "Event 6494e0ac-dfcb-11e5-88c1-472e84a9cbee was deleted",
  "links": { "about": "https://cozy.github.io/cozy-stack/errors.md#deleted" }
}

possible errors :

Access multiple documents at once

Request

POST /data/:type/_all_docs HTTP/1.1
POST /data/io.cozy.files/_all_docs?include_docs=true HTTP/1.1
Content-Length: ...
Content-Type: application/json
Accept: application/json
{
  "keys": [
    "7f46ed4ed2a775494da3b0b44e00314f",
    "7f46ed4ed2a775494da3b0b44e003b18"
  ]
}

Response OK

HTTP/1.1 200 OK
Date: Mon, 27 Sept 2016 12:28:53 GMT
Content-Length: ...
Content-Type: application/json
Etag: "3-6494e0ac6494e0ac"
{
  "total_rows": 11,
  "rows": [
    {
      "id": "7f46ed4ed2a775494da3b0b44e00314f",
      "key": "7f46ed4ed2a775494da3b0b44e00314f",
      "value": {
        "rev": "1-870e58f8a1b2130c3a41e767f9c7d93a"
      },
      "doc": {
        "_id": "7f46ed4ed2a775494da3b0b44e00314f",
        "_rev": "1-870e58f8a1b2130c3a41e767f9c7d93a",
        "type": "directory",
        "name": "Uploaded from Cozy Photos",
        "dir_id": "7f46ed4ed2a775494da3b0b44e0027df",
        "created_at": "2017-07-04T06:49:12.844631837Z",
        "updated_at": "2017-07-04T06:49:12.844631837Z",
        "tags": [],
        "path": "/Photos/Uploaded from Cozy Photos"
      }
    },
    {
      "key": "7f46ed4ed2a775494da3b0b44e003b18",
      "error": "not_found"
    }
  ]
}

possible errors :

Details

When some keys don’t match an existing document, the response still has a status 200 and the errors are included in the rows field (see above, same behavior as CouchDB).

Create a document

Request

POST /data/:type/ HTTP/1.1
POST /data/io.cozy.events/ HTTP/1.1
Content-Length: ...
Content-Type: application/json
Accept: application/json
{
  "startdate": "20160712T150000",
  "enddate": "20160712T150000"
}

Response OK

HTTP/1.1 201 Created
Content-Length: ...
Content-Type: application/json
{
  "id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee",
  "type": "io.cozy.events",
  "ok": true,
  "rev": "1-6494e0ac6494e0ac",
  "data": {
    "_id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee",
    "_type": "io.cozy.events",
    "_rev": "1-6494e0ac6494e0ac",
    "startdate": "20160712T150000",
    "enddate": "20160712T150000"
  }
}

possible errors :

Details

Update an existing document

Request

PUT /data/:type/:id HTTP/1.1
PUT /data/io.cozy.events/6494e0ac-dfcb-11e5-88c1-472e84a9cbee HTTP/1.1
Content-Length: ...
Content-Type: application/json
Accept: application/json
{
  "_id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee",
  "_type": "io.cozy.events",
  "_rev": "1-6494e0ac6494e0ac",
  "startdate": "20160712T150000",
  "enddate": "20160712T200000"
}

Response OK

HTTP/1.1 200 OK
Content-Length: ...
Content-Type: application/json
{
  "id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee",
  "type": "io.cozy.events",
  "ok": true,
  "rev": "2-056f5f44046ecafc08a2bc2b9c229e20",
  "data": {
    "_id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee",
    "_type": "io.cozy.events",
    "_rev": "2-056f5f44046ecafc08a2bc2b9c229e20",
    "startdate": "20160712T150000",
    "enddate": "20160712T200000"
  }
}

Possible errors :

Conflict prevention

The client MUST give a _rev field in the document. If this field is different from the one in the current version of the document, an error 409 Conflict will be returned.

Details

Create a document with a fixed id

Request

PUT /data/:type/:id HTTP/1.1
PUT /data/io.cozy.events/6494e0ac-dfcb-11e5-88c1-472e84a9cbee HTTP/1.1
Content-Length: ...
Content-Type: application/json
Accept: application/json
{
  "startdate": "20160712T150000",
  "enddate": "20160712T200000"
}

Response OK

HTTP/1.1 200 OK
Content-Length: ...
Content-Type: application/json
{
  "id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee",
  "type": "io.cozy.events",
  "ok": true,
  "rev": "1-056f5f44046ecafc08a2bc2b9c229e20",
  "data": {
    "_id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee",
    "_type": "io.cozy.events",
    "_rev": "1-056f5f44046ecafc08a2bc2b9c229e20",
    "startdate": "20160712T150000",
    "enddate": "20160712T200000"
  }
}

Possible errors :

Details

Delete a document

Request

DELETE /data/:type/:id?rev=:rev HTTP/1.1
DELETE /data/io.cozy.events/6494e0ac-dfcb-11e5-88c1-472e84a9cbee?rev=1-82a7144c9ec228c9a851b8a1c1aa225b HTTP/1.1
Accept: application/json

Response OK

HTTP/1.1 200 OK
Content-Length: ...
Content-Type: application/json
{
  "id": "6494e0ac-dfcb-11e5-88c1-472e84a9cbee",
  "type": "io.cozy.events",
  "ok": true,
  "rev": "2-056f5f44046ecafc08a2bc2b9c229e20",
  "_deleted": true
}

Possible errors :

Conflict prevention

It is possible to use either a rev query string parameter or a HTTP If-Match header to prevent conflict on deletion:

Details

List all the documents

Request

GET /data/io.cozy.events/_all_docs?include_docs=true HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "offset": 0,
  "rows": [
    {
      "id": "16e458537602f5ef2a710089dffd9453",
      "key": "16e458537602f5ef2a710089dffd9453",
      "value": {
        "rev": "1-967a00dff5e02add41819138abb3284d"
      },
      "doc": {
        "field": "value"
      }
    },
    {
      "id": "f4ca7773ddea715afebc4b4b15d4f0b3",
      "key": "f4ca7773ddea715afebc4b4b15d4f0b3",
      "value": {
        "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
      },
      "doc": {
        "field": "other-value"
      }
    }
  ],
  "total_rows": 2
}

Details

See _all_docs in couchdb docs

List the known doctypes

Request

GET /data/_all_doctypes HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json
["io.cozy.files", "io.cozy.jobs", "io.cozy.triggers", "io.cozy.settings"]

Others