Records¶
Records belong to a collection. It is the data being stored and synchronised.
A record is a mapping with the following attributes:
data
: attributes of the record objectid
: the record object idlast_modified
: the timestamp of the last modification
permissions
: the ACLs for the collection object
Uploading a record¶
-
POST
/buckets/
(bucket_id)/collections/
(collection_id)/records
¶ synopsis: Store a record in the collection. The ID will be assigned automatically. Requires authentication
Example Request
$ echo '{"data": {"foo": "bar"}}' | http post http://localhost:8888/v1/buckets/blog/collections/articles/records --auth="token:bob-token" --verbose
POST /v1/buckets/blog/collections/articles/records HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Content-Length: 25 Content-Type: application/json Host: localhost:8888 User-Agent: HTTPie/0.9.2 { "data": { "foo": "bar" } }
Example Response
HTTP/1.1 201 Created Access-Control-Expose-Headers: Backoff, Retry-After, Alert Content-Length: 199 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 17:02:23 GMT Server: waitress { "data": { "foo": "bar", "id": "89881454-e4e9-4ef0-99a9-404d95900352", "last_modified": 1434646943915 }, "permissions": { "write": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } }
If the If-Match: "<timestamp>"
request header is provided as described in
the section about timestamps, and if the list has
changed meanwhile, a 412 Precondition Failed
error is returned.
If the If-None-Match: *
request header is provided, and if the provided data
contains an id
field, and if there is already an existing object with this id
,
a 412 Precondition Failed
error is returned.
Important
If the posted object has an id
field, it will be taken into account.
However, if a object already exists with the same id
, a 200 OK
response
is returned with the existing object in body (instead of 201 Created
).
See https://github.com/Kinto/kinto/issues/140
Validation¶
If the posted values are invalid (e.g. field value is not an integer)
an error response is returned with 400 Bad Request
.
Permissions¶
In the JSON request payloads, an optional permissions
attribute can be provided.
The current user id is always added among the write
principals.
HTTP Status Codes¶
200 OK
: This object already exists, the one stored on the database is returned201 Created
: The object was created400 Bad Request
: The request body is invalid401 Unauthorized
: The request is missing authentication headers401 Forbidden
: The user is not allowed to perform the operation, or the resource is not accessible406 Not Acceptable
: The client doesn’t accept supported responses Content-Type412 Precondition Failed
: List has changed since value inIf-Match
header415 Unsupported Media Type
: The client request was not sent with a correct Content-Type
Replacing a record¶
-
PUT
/buckets/
(bucket_id)/collections/
(collection_id)/records/
(record_id)¶ Synopsis: Create or update a record in the collection. The POST body is a JSON mapping containing:
data
: the fields of the record;permissions
: optional a json dict containing the permissions for the record to be created.
Requires authentication
Example Request
$ echo '{"data": {"foo": "baz"}}' | http put http://localhost:8888/v1/buckets/blog/collections/articles/records/89881454-e4e9-4ef0-99a9-404d95900352 --auth="token:bob-token" --verbose
PUT /v1/buckets/blog/collections/articles/records/89881454-e4e9-4ef0-99a9-404d95900352 HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Content-Length: 25 Content-Type: application/json Host: localhost:8888 User-Agent: HTTPie/0.9.2 { "data": { "foo": "baz" } }
Example Response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Backoff, Retry-After, Alert Content-Length: 199 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 17:16:22 GMT Server: waitress { "data": { "foo": "baz", "id": "89881454-e4e9-4ef0-99a9-404d95900352", "last_modified": 1434647782623 }, "permissions": { "write": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } }
Validation and conflicts behaviour is similar to creating objects (POST
).
If the If-Match: "<timestamp>"
request header is provided as described in
the section about timestamps, and if the object has
changed meanwhile, a 412 Precondition Failed
error is returned.
If the If-None-Match: *
request header is provided and if there is already
an existing object with this id
, a 412 Precondition Failed
error is returned.
Permissions¶
In the JSON request payloads, at least one of data
and permissions
must be provided. Permissions can thus be replaced independently from data.
In the case of creation, if only permissions
is provided, an empty object is created.
The current user id is always added among the write
principals.
HTTP Status Code¶
201 Created
: The object was created200 OK
: The object was replaced400 Bad Request
: The request body is invalid401 Unauthorized
: The request is missing authentication headers401 Forbidden
: The user is not allowed to perform the operation, or the resource is not accessible406 Not Acceptable
: The client doesn’t accept supported responses Content-Type.412 Precondition Failed
: Record was changed or deleted since value inIf-Match
header.415 Unsupported Media Type
: The client request was not sent with a correct Content-Type.
Updating a record¶
-
PATCH
/buckets/
(bucket_id)/collections/
(collection_id)/records/
(record_id)¶ Synopsis: Update a record in the collection. Specify only the fields to be modified (all the rest will remain intact). Requires authentication
Example Request
$ echo '{"data": {"status": "done"}}' | http patch http://localhost:8888/v1/buckets/blog/collections/articles/records/89881454-e4e9-4ef0-99a9-404d95900352 --auth="token:bob-token" --verbose
PATCH /v1/buckets/blog/collections/articles/records/89881454-e4e9-4ef0-99a9-404d95900352 HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Content-Length: 25 Content-Type: application/json Host: localhost:8888 User-Agent: HTTPie/0.9.2 { "data": { "status": "done" } }
Example Response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Backoff, Retry-After, Alert Content-Length: 211 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 17:19:56 GMT Server: waitress { "data": { "status": "done", "title": "Midnight in Paris", "id": "89881454-e4e9-4ef0-99a9-404d95900352", "last_modified": 1434647996969 }, "permissions": { "write": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } }
If the object is missing (or already deleted), a 404 Not Found
error is returned.
The consumer might decide to ignore it.
If the If-Match: "<timestamp>"
request header is provided as described in
the section about timestamps, and if the object has
changed meanwhile, a 412 Precondition Failed
error is returned.
Note
last_modified
is updated to the current server timestamp, only if a
field value was changed.
Attributes merge¶
The provided values are merged with the existing object. For example:
{"a":"b"}
+{"a":"c"}
→{"a":"c"}
{"a":"b"}
+{"b":"c"}
→{"a":"b", "b":"c"}
{"a":"b"}
+{"a":null}
→{"a":null}
: attributes can’t be removed with patch{"a": {"b":"c"}}
+{"a":{"d":"e"}}
→{"a":{"d":"e"}}
: sub-objects are replaced, not merged
Note
JSON-Patch or JSON merge are currently not supported. Any help is welcomed though! See https://github.com/Kinto/kinto/issues/623
Light response body¶
If a Response-Behavior
request header is set to light
,
only the fields whose value was changed are returned. If set to
diff
, only the fields whose value became different than
the one provided are returned.
Permissions¶
In the JSON request payloads, at least one of data
and permissions
must be provided. Permissions can thus be modified independently from data.
The current user id is always added among the write
principals.
HTTP Status Codes¶
200 OK
: The object was modified400 Bad Request
: The request body is invalid, or a read-only field was modified401 Unauthorized
: The request is missing authentication headers401 Forbidden
: The user is not allowed to perform the operation, or the resource is not accessible401 Forbidden
: The object does not exist or was deleted406 Not Acceptable
: The client doesn’t accept supported responses Content-Type.412 Precondition Failed
: Record changed since value inIf-Match
header415 Unsupported Media Type
: The client request was not sent with a correct Content-Type.
Retrieving stored records¶
-
GET
/buckets/
(bucket_id)/collections/
(collection_id)/records
¶ Synopsis: Retrieve all the records in the collection. Requires authentication
Example Request
$ http get http://localhost:8888/v1/buckets/blog/collections/articles/records --auth="token:bob-token" --verbose
GET /v1/buckets/blog/collections/articles/records HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Host: localhost:8888 User-Agent: HTTPie/0.9.2
HTTP/1.1 200 OK Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Next-Page, Total-Records, Last-Modified, ETag Content-Length: 110 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 17:24:38 GMT Etag: "1434648278603" Last-Modified: Thu, 18 Jun 2015 17:24:38 GMT Server: waitress Total-Records: 1 { "data": [ { "baz": "bar", "foo": "baz", "id": "89881454-e4e9-4ef0-99a9-404d95900352", "last_modified": 1434647996969 } ] }
Retrieving a specific record¶
-
GET
/buckets/
(bucket_id)/collections/
(collection_id)/records/
(record_id)¶ Synopsis: Retrieve a specific record by its ID. Requires authentication
Example Request
$ http get http://localhost:8888/v1/buckets/blog/collections/articles/records/89881454-e4e9-4ef0-99a9-404d95900352 --auth="token:bob-token" --verbose
GET /v1/buckets/blog/collections/articles/records/89881454-e4e9-4ef0-99a9-404d95900352 HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Host: localhost:8888 User-Agent: HTTPie/0.9.2
Example Response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Last-Modified, ETag Content-Length: 211 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 17:29:59 GMT Etag: "1434648599199" Last-Modified: Thu, 18 Jun 2015 17:29:59 GMT Server: waitress { "data": { "baz": "bar", "foo": "baz", "id": "89881454-e4e9-4ef0-99a9-404d95900352", "last_modified": 1434647996969 }, "permissions": { "write": [ "basicauth:206691a25679e4e1135f16aa77ebcf211c767393c4306cfffe6cc228ac0886b6" ] } }
Delete stored records¶
-
DELETE
/buckets/
(bucket_id)/collections/
(collection_id)/records
¶ Synopsis: Delete all the records in the collection. Requires authentication
Example Request
$ http delete http://localhost:8888/v1/buckets/blog/collections/articles/records --auth="token:bob-token" --verbose
DELETE /v1/buckets/blog/collections/articles/records HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Host: localhost:8888 User-Agent: HTTPie/0.9.2
Example Response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Last-Modified, ETag Content-Length: 211 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 17:29:59 GMT Etag: "1434648599199" Last-Modified: Thu, 18 Jun 2015 17:29:59 GMT Server: waitress { "data": [{ "deleted": true, "id": "89881454-e4e9-4ef0-99a9-404d95900352", "last_modified": 1434648749173 }] }
Deleting a single record¶
-
DELETE
/buckets/
(bucket_id)/collections/
(collection_id)/records/
(record_id)¶ Synopsis: Delete a record by its ID. Example Request
$ http delete http://localhost:8888/v1/buckets/blog/collections/articles/records/89881454-e4e9-4ef0-99a9-404d95900352 --auth="token:bob-token" --verbose
DELETE /v1/buckets/blog/collections/articles/records/89881454-e4e9-4ef0-99a9-404d95900352 HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Basic Ym9iOg== Connection: keep-alive Content-Length: 0 Host: localhost:8888 User-Agent: HTTPie/0.9.2
Example Response
HTTP/1.1 200 OK Access-Control-Expose-Headers: Backoff, Retry-After, Alert Content-Length: 99 Content-Type: application/json; charset=UTF-8 Date: Thu, 18 Jun 2015 17:32:29 GMT Server: waitress { "data": { "deleted": true, "id": "89881454-e4e9-4ef0-99a9-404d95900352", "last_modified": 1434648749173 } }