First steps with Kinto HTTP API

There are several kinds of applications where Kinto is particulary relevant as a storage backend.

The following tutorial should provide enough information to understand how to:

  • Sync user data between devices;
  • Sync and share data between users, leveraging permissions.

Important

In this tutorial we will use a Basic Authentication, which computes a user id based on the token provided in the request.

This method has many limitations but has the advantage to avoid specific setup or third-party services to get started immediately.

Read more about authentication in Kinto.

Sync user data between devices

Let’s say that we want to do a TodoMVC backend that will sync user tasks between the devices.

In order to separate data between each user, we will use the default personal bucket.

Unlike other buckets, the collections in the default bucket are created implicitly.

We’ll start with a relatively simple data model:

  • description: A string describing the task
  • status: The status of the task, (e.g. todo, doing or done).

Using the httpie tool we can post a sample record in the tasks collection:

Note

Please consider reading httpie documentation for more information If you need to configure a proxy for instance.

We use the Mozilla demo server:

$ echo '{"data": {"description": "Write a tutorial explaining Kinto", "status": "todo"}}' | \
    http POST https://kinto.dev.mozaws.net/v1/buckets/default/collections/tasks/records \
         -v --auth 'token:my-secret'
HTTP/1.1 201 Created
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Backoff: 10
Connection: keep-alive
Content-Length: 253
Content-Type: application/json; charset=UTF-8
Date: Mon, 06 Jul 2015 08:39:56 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "description": "Write a tutorial explaining Kinto",
        "id": "a5f490b2-218e-4d71-ac5a-f046ae285c55",
        "last_modified": 1436171996916,
        "status": "todo"
    },
    "permissions": {
        "write": [
            "basicauth:10ea4e5fbf849196a4fe8a9c250b737dd5ef17abbeb8f99692d62828465a9823"
        ]
    }
}

Note

With Basic Auth a unique identifier needs to be associated with each user. This identifier is built using the token value provided in the request. Therefore users cannot change their password easily without losing access to their data. More information.

Let us fetch our new collection of tasks:

$ http GET https://kinto.dev.mozaws.net/v1/buckets/default/collections/tasks/records \
       -v --auth 'token:my-secret'
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Next-Page, Total-Records, Last-Modified, ETag
Backoff: 10
Connection: keep-alive
Content-Length: 152
Content-Type: application/json; charset=UTF-8
Date: Mon, 06 Jul 2015 08:40:14 GMT
ETag: "1436171996916"
Last-Modified: Mon, 06 Jul 2015 08:39:56 GMT
Server: nginx/1.4.6 (Ubuntu)
Total-Records: 1

{
    "data": [
        {
            "description": "Write a tutorial explaining Kinto",
            "id": "a5f490b2-218e-4d71-ac5a-f046ae285c55",
            "last_modified": 1436171996916,
            "status": "todo"
        }
    ]
}

Keep a note of the ETag and of the last_modified values returned (here both "1436171996916") - we’ll need them for a later example.

We can also update one of our tasks using its id:

$ echo '{"data": {"status": "doing"}}' | \
     http PATCH https://kinto.dev.mozaws.net/v1/buckets/default/collections/tasks/records/a5f490b2-218e-4d71-ac5a-f046ae285c55 \
          -v  --auth 'token:my-secret'
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Backoff: 10
Connection: keep-alive
Content-Length: 254
Content-Type: application/json; charset=UTF-8
Date: Mon, 06 Jul 2015 08:43:49 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "description": "Write a tutorial explaining Kinto",
        "id": "a5f490b2-218e-4d71-ac5a-f046ae285c55",
        "last_modified": 1436172229372,
        "status": "doing"
    },
    "permissions": {
        "write": [
            "basicauth:10ea4e5fbf849196a4fe8a9c250b737dd5ef17abbeb8f99692d62828465a9823"
        ]
    }
}

Here you should ask yourself: what happens if another device updated the same record in the interim - will this request overwrite those changes?

With the request shown above the answer is yes.

If you want the server to reject changes if the record was modified in the interim, you must send the If-Match header.

In the If-Match header, you must send the ETag header value you obtained while fetching the collection.

Let’s try to modify the record using an obsolete value of ETag (obtained while we fetched the collection earlier - you kept a note, didn’t you?):

$ echo '{"data": {"status": "done"}}' | \
    http PATCH https://kinto.dev.mozaws.net/v1/buckets/default/collections/tasks/records/a5f490b2-218e-4d71-ac5a-f046ae285c55 \
        If-Match:'"1434641515332"' \
        -v  --auth 'token:my-secret'
HTTP/1.1 412 Precondition Failed
Connection: keep-alive
Content-Length: 98
Content-Type: application/json; charset=UTF-8
Date: Mon, 06 Jul 2015 08:45:07 GMT
ETag: "1436172229372"
Last-Modified: Mon, 06 Jul 2015 08:43:49 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "code": 412,
    "errno": 114,
    "error": "Precondition Failed",
    "message": "Resource was modified meanwhile"
}

As expected here, the server rejects the modification with a 412 Precondition Failed error response.

In order to update this record safely we can fetch the last version of this single record and merge attributes locally:

$ http GET https://kinto.dev.mozaws.net/v1/buckets/default/collections/tasks/records/a5f490b2-218e-4d71-ac5a-f046ae285c55 \
       -v  --auth 'token:my-secret'
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Last-Modified, ETag
Backoff: 10
Connection: keep-alive
Content-Length: 254
Content-Type: application/json; charset=UTF-8
Date: Mon, 06 Jul 2015 08:45:57 GMT
ETag: "1436172229372"
Last-Modified: Mon, 06 Jul 2015 08:43:49 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "description": "Write a tutorial explaining Kinto",
        "id": "a5f490b2-218e-4d71-ac5a-f046ae285c55",
        "last_modified": 1436172229372,
        "status": "doing"
    },
    "permissions": {
        "write": [
            "basicauth:10ea4e5fbf849196a4fe8a9c250b737dd5ef17abbeb8f99692d62828465a9823"
        ]
    }
}

The strategy to merge local changes is left to the client and might depend on the client specifications. A three-way merge is possible when changes do not affect the same fields or if both objects are equal. Prompting the user to decide what version should be kept might also be an option.

Note

Do not run away! You will most likely use Kinto/kinto.js, which provides nice abstractions to interact with the Kinto API.

Once merged, we can send back again our modifications using the last record ETag value:

$ echo '{"data": {"status": "done"}}' | \
    http PATCH https://kinto.dev.mozaws.net/v1/buckets/default/collections/tasks/records/a5f490b2-218e-4d71-ac5a-f046ae285c55 \
        If-Match:'"1436172229372"' \
        -v  --auth 'token:my-secret'
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Backoff: 10
Connection: keep-alive
Content-Length: 253
Content-Type: application/json; charset=UTF-8
Date: Mon, 06 Jul 2015 08:47:22 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "description": "Write a tutorial explaining Kinto",
        "id": "a5f490b2-218e-4d71-ac5a-f046ae285c55",
        "last_modified": 1436172442466,
        "status": "done"
    },
    "permissions": {
        "write": [
            "basicauth:10ea4e5fbf849196a4fe8a9c250b737dd5ef17abbeb8f99692d62828465a9823"
        ]
    }
}

You can also delete the record and use the same mechanism to avoid conflicts:

$ http DELETE https://kinto.dev.mozaws.net/v1/buckets/default/collections/tasks/records/a5f490b2-218e-4d71-ac5a-f046ae285c55 \
       If-Match:'"1436172442466"' \
       -v  --auth 'token:my-secret'
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Backoff: 10
Connection: keep-alive
Content-Length: 99
Content-Type: application/json; charset=UTF-8
Date: Mon, 06 Jul 2015 08:48:21 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "deleted": true,
        "id": "a5f490b2-218e-4d71-ac5a-f046ae285c55",
        "last_modified": 1436172501156
    }
}

Likewise, we can query the list of changes (updates and deletions) that occured since we last fetched the collection.

Just add the _since querystring filter, using the value of any ETag (or last_modified data field):

$ http GET https://kinto.dev.mozaws.net/v1/buckets/default/collections/tasks/records?_since="1434642603605" \
       -v  --auth 'token:my-secret'
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Next-Page, Total-Records, Last-Modified, ETag
Backoff: 10
Connection: keep-alive
Content-Length: 101
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 16:29:54 GMT
ETag: "1434641474977"
Last-Modified: Thu, 18 Jun 2015 15:31:14 GMT
Server: nginx/1.4.6 (Ubuntu)
Total-Records: 0

{
    "data": [
        {
            "deleted": true,
            "id": "a5f490b2-218e-4d71-ac5a-f046ae285c55",
            "last_modified": 1434644823180
        }
    ]
}

The list will be empty if no change occurred. If you would prefer to receive a 304 Not Modified response in this case, simply send the If-None-Match header with the last ETag value.

Sync and share data between users

In this example, instead of using the personal bucket we will create an application-specific bucket called todo.

$ http PUT https://kinto.dev.mozaws.net/v1/buckets/todo \
    -v --auth 'token:my-secret'
HTTP/1.1 201 Created
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Backoff: 10
Connection: keep-alive
Content-Length: 155
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 16:33:17 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "id": "todo",
        "last_modified": 1434645197868
    },
    "permissions": {
        "write": [
            "basicauth:10ea4e5fbf849196a4fe8a9c250b737dd5ef17abbeb8f99692d62828465a9823"
        ]
    }
}

By default the creator is granted sole administrator privileges (see write permission). In order to allow collaboration additional permissions will need to be added.

In our case, we want people to be able to create and share tasks, so we will create a tasks collection with the record:create permission for authenticated users (i.e. system.Authenticated):

$ echo '{"permissions": {"record:create": ["system.Authenticated"]}}' | \
    http PUT https://kinto.dev.mozaws.net/v1/buckets/todo/collections/tasks \
        -v --auth 'token:my-secret'
HTTP/1.1 201 Created
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Backoff: 10
Connection: keep-alive
Content-Length: 197
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 16:37:48 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "id": "tasks",
        "last_modified": 1434645468367
    },
    "permissions": {
        "record:create": [
            "system.Authenticated"
        ],
        "write": [
            "basicauth:10ea4e5fbf849196a4fe8a9c250b737dd5ef17abbeb8f99692d62828465a9823"
        ]
    }
}

Note

As you may noticed, you are automatically added to the write permission of any objects you create.

Now Alice can create a task in this collection:

$ echo '{"data": {"description": "Alice task", "status": "todo"}}' | \
    http POST https://kinto.dev.mozaws.net/v1/buckets/todo/collections/tasks/records \
    -v --auth 'token:alice-token'
HTTP/1.1 201 Created
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Backoff: 10
Connection: keep-alive
Content-Length: 231
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 16:41:50 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "description": "Alice task",
        "id": "2fa91620-f4fa-412e-aee0-957a7ad2dc0e",
        "last_modified": 1434645840590,
        "status": "todo"
    },
    "permissions": {
        "write": [
            "basicauth:9be2b51de8544fbed4539382d0885f8643c0185c90fb23201d7bbe86d70b4a44"
        ]
    }
}

And Bob can also create a task:

$ echo '{"data": {"description": "Bob new task", "status": "todo"}}' | \
    http POST https://kinto.dev.mozaws.net/v1/buckets/todo/collections/tasks/records \
    -v --auth 'token:bob-token'
HTTP/1.1 201 Created
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Backoff: 10
Connection: keep-alive
Content-Length: 232
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 16:44:39 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "description": "Bob new task",
        "id": "10afe152-b5bb-4aff-b77e-10be44587057",
        "last_modified": 1434645879088,
        "status": "todo"
    },
    "permissions": {
        "write": [
            "basicauth:a103c2e714a04615783de8a03fef1c7fee221214387dd07993bb9aed1f2f2148"
        ]
    }
}

If Alice wants to share a task with Bob, she can give him the read permission on her records:

$ echo '{"permissions": {
    "read": ["basicauth:a103c2e714a04615783de8a03fef1c7fee221214387dd07993bb9aed1f2f2148"]
}}' | \
http PATCH https://kinto.dev.mozaws.net/v1/buckets/todo/collections/tasks/records/2fa91620-f4fa-412e-aee0-957a7ad2dc0e \
    -v --auth 'token:alice-token'
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Backoff: 10
Connection: keep-alive
Content-Length: 273
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 16:50:57 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "id": "2fa91620-f4fa-412e-aee0-957a7ad2dc0e",
        "last_modified": 1434646257547
        "description": "Alice task",
        "status": "todo"
    },
    "permissions": {
        "read": [
            "basicauth:a103c2e714a04615783de8a03fef1c7fee221214387dd07993bb9aed1f2f2148"
        ],
        "write": [
            "basicauth:9be2b51de8544fbed4539382d0885f8643c0185c90fb23201d7bbe86d70b4a44"
        ]
    }
}

If Bob want’s to get the record list, he will get his records as well as Alice’s ones:

$ http GET https://kinto.dev.mozaws.net/v1/buckets/todo/collections/tasks/records \
       -v --auth 'token:bob-token'
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Content-Length, Next-Page, Total-Records, Last-Modified, ETag
Content-Length: 371
Content-Type: application/json; charset=UTF-8
Etag: "1434646257547"
Total-Records: 3

{
    "data": [
        {
            "description": "Bob new task",
            "id": "10afe152-b5bb-4aff-b77e-10be44587057",
            "last_modified": 1434645879088,
            "status": "todo"
        },
        {
            "description": "Alice task",
            "id": "2fa91620-f4fa-412e-aee0-957a7ad2dc0e",
            "last_modified": 1434646257547,
            "status": "todo"
        }
    ]
}

Working with groups

To go further, you may want to allow users to share data with a group of users.

Let’s add the permission for authenticated users to create groups in the todo bucket:

$ echo '{"permissions": {"group:create": ["system.Authenticated"]}}' | \
    http PATCH https://kinto.dev.mozaws.net/v1/buckets/todo \
        -v --auth 'token:my-secret'
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Backoff: 10
Connection: keep-alive
Content-Length: 195
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 16:59:29 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "id": "todo",
        "last_modified": 1434646769990
    },
    "permissions": {
        "group:create": [
            "system.Authenticated"
        ],
        "write": [
            "basicauth:10ea4e5fbf849196a4fe8a9c250b737dd5ef17abbeb8f99692d62828465a9823"
        ]
    }
}

Now Alice can create a group of her friends (Bob and Mary):

$ echo '{"data": {
    "members": ["basicauth:a103c2e714a04615783de8a03fef1c7fee221214387dd07993bb9aed1f2f2148",
                "basicauth:8d1661a89bd2670f3c42616e3527fa30521743e4b9825fa4ea05adc45ef695b6"]
}}' | http PUT https://kinto.dev.mozaws.net/v1/buckets/todo/groups/alice-friends \
    -v --auth 'token:alice-token'
HTTP/1.1 201 Created
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Backoff: 10
Connection: keep-alive
Content-Length: 330
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 17:03:24 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "id": "alice-friends",
        "last_modified": 1434647004644,
        "members": [
            "basicauth:a103c2e714a04615783de8a03fef1c7fee221214387dd07993bb9aed1f2f2148",
            "basicauth:8d1661a89bd2670f3c42616e3527fa30521743e4b9825fa4ea05adc45ef695b6"
        ]
    },
    "permissions": {
        "write": [
            "basicauth:9be2b51de8544fbed4539382d0885f8643c0185c90fb23201d7bbe86d70b4a44"
        ]
    }
}

Now Alice can share records directly with her group of friends:

$ echo '{
    "permissions": {
        "read": ["/buckets/todo/groups/alice-friends"]
    }
}' | \
http PATCH https://kinto.dev.mozaws.net/v1/buckets/todo/collections/tasks/records/2fa91620-f4fa-412e-aee0-957a7ad2dc0e \
    -v --auth 'token:alice-token'
HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Backoff: 10
Connection: keep-alive
Content-Length: 237
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 17:06:09 GMT
Server: nginx/1.4.6 (Ubuntu)

{
    "data": {
        "id": "2fa91620-f4fa-412e-aee0-957a7ad2dc0e",
        "last_modified": 1434647169157
    },
    "permissions": {
        "read": [
            "basicauth:a103c2e714a04615783de8a03fef1c7fee221214387dd07993bb9aed1f2f2148",
            "/buckets/todo/groups/alice-friends"
        ],
        "write": [
            "basicauth:9be2b51de8544fbed4539382d0885f8643c0185c90fb23201d7bbe86d70b4a44"
        ]
    }
}

And now Mary can access the record:

$ http GET https://kinto.dev.mozaws.net/v1/buckets/todo/collections/tasks/records/2fa91620-f4fa-412e-aee0-957a7ad2dc0e \
    -v --auth 'token:mary-token'

Note

The records of the personal bucket can also be shared! In order to obtain its ID, just use GET /buckets/default and then share its content using the full URL (e.g. /buckets/b86b26b8-be36-4eaa-9ed9-2e6de63a5252)!

Conclusion

In this tutorial you have seen some of the concepts exposed by Kinto:

  • Using the default personal user bucket
  • Handling synchronisation and conflicts
  • Creating a bucket to share data between users
  • Creating groups, collections and records
  • Modifying objects permissions, for users and groups

More details about permissions, HTTP API headers and status codes.

Note

We plan to improve our documentation and make sure it is as easy as possible to get started with Kinto.

Please do not hesitate to give us feedback, and if you are interested in making improvements, you’re welcome to join us!