Get a list of records for a collection¶

Requires authentication

Returns all records of the current user for this collection.

Collection can be one of the Firefox Sync collections:

The default collections used by Firefox to store sync data are:

• bookmarks
• history
• forms
• prefs
• tabs
• passwords

The following additional collections are used for internal management purposes by the storage client:

• clients
• crypto
• keys
• meta

The returned value is a JSON mapping containing:

• data: the list of records, with exhaustive fields;

A Total-Records response header indicates the total number of records in the collection.

A Last-Modified response header provides a human-readable (rounded to second) version of the current collection timestamp.

For cache and concurrency control, an ETag response header gives the value that consumers can provide in subsequent requests using If-Match and If-None-Match headers (see the section about timestamps).

GET /buckets/syncto/collections/(collection_id)/records¶

Example request:

$ BID_AUDIENCE=https://token.services.mozilla.com/ BID_WITH_CLIENT_STATE=True \
    http GET https://syncto.dev.mozaws.net/v1/buckets/syncto/collections/history/records \
        --auth-type fxa-browserid --auth "user@email.com:P4S5W0RD" -v

GET /v1/buckets/syncto/collections/history/records HTTP/1.1
Authorization: BrowserID eyJhbGciOiJSUzI1NiJ9...FHGg
Host: syncto.dev.mozaws.net
User-Agent: HTTPie/0.9.2
X-Client-State: 64e8bc35e90806f9a67c0ef8fef63...

Example response:

HTTP/1.1 200 OK
Access-Control-Expose-Headers: Content-Length, Quota-Remaining, Alert, \
    Retry-After, Last-Modified, Total-Records, ETag, Backoff, Next-Page
Content-Length: 1680
Content-Type: application/json; charset=UTF-8
Date: Tue, 06 Oct 2015 13:57:24 GMT
ETag: "1442849064460"
Last-Modified: Mon, 21 Sep 2015 15:24:24 GMT
Total-Records: 6

{
    "data": [
        {
            "id": "VLkOS7iT5C94",
            "last_modified": 1441868927070,
            "payload": "{\"ciphertext\":\"Wf2AoZiOly...\",\"IV\":\"jW7JFPf...\",\"hmac\":\"989352d9b5e0c6...\"}",
            "sortindex": -1
        },
        {
            "id": "qYYobAN_p9vS",
            "last_modified": 1441868927070,
            "payload": "{\"ciphertext\":\"3upjoLrO...7\",\"IV\":\"3O/nPq82xUT...\",\"hmac\":\"addce0f9d3024ed9fd0042b...\"}",
            "sortindex": 100
        },
        ...
    ]
}

Status Codes:	200 OK – The request was processed. 304 Not Modified – The collection did not change since value in If-None-Match header 400 Bad Request – The request querystring is invalid 401 Unauthorized – Something went wrong with your authentication 412 Precondition Failed – Collection changed since value in If-Match header

Get a collection record¶

Requires authentication

Returns a specific record by its id. The GET response body is a JSON mapping containing:

• data: the record with exhaustive schema fields;

IDs are kept between Firefox Sync and Syncto.

Firefox Sync IDs are generated on client side as 9 random Bytes encoded in urlsafe base64 (+ and / are replaced with - and _).

If the request header If-None-Match is provided, and if the record has not changed meanwhile, a 304 Not Modified is returned.

GET /buckets/syncto/collections/(collection_id)/records/(record_id)¶

Example request:

$ http GET \
    https://syncto.dev.mozaws.net/v1/buckets/syncto/collections/history/records/d2X1O6-DyeFS \
    Authorization:"BrowserID eyJhbGciOiJSUzI1NiJ9...i_dQ" \
    X-Client-State:64e8bc35e90806f9a67c0ef8fef63...

GET /v1/buckets/syncto/collections/history/records/d2X1O6-DyeFS HTTP/1.1
Authorization: BrowserID eyJhbGciOiJSUzI1NiJ9...i_dQ
Host: syncto.dev.mozaws.net
User-Agent: HTTPie/0.9.2
X-Client-State: 64e8bc35e90806f9a67c0ef8fef63...

Example response:

HTTP/1.1 200 OK
Access-Control-Expose-Headers: Content-Length, Alert, Retry-After, Last-Modified, ETag, Backoff
Content-Length: 289
Content-Type: application/json; charset=UTF-8
Date: Tue, 06 Oct 2015 14:18:40 GMT
ETag: "1441868927070"
Last-Modified: Thu, 10 Sep 2015 07:08:47 GMT

{
    "data": {
        "id": "d2X1O6-DyeFS",
        "last_modified": 1441868927070,
        "payload": "{\"ciphertext\":\"75IcW3P4WxUJipehWryevc+ygK5vojh3n...\",\"IV\":\"Sj3U2Nkk2IjE...\",\"hmac\":\"c6a530f348...b68b610351\"}",
        "sortindex": 2000
    }
}

Status Codes:	200 OK – The request was processed. 304 Not Modified – The collection did not change since value in If-None-Match header 401 Unauthorized – Something went wrong with your authentication 412 Precondition Failed – Collection changed since value in If-Match header

Delete a record¶

Requires authentication

Delete a specific record by its id.

Note that contrary to what Kinto does, Firefox Sync count on clients to create deleted records tombstones. Moreover Firefox Sync tombstones are encrypted and look like real records for Syncto.

This endpoint should not be used to create tombstones but to remove the record when the client decides that all clients already fetched the tombstone.

By default this endpoint is deactivated and should be activated on a per collection basis.

DELETE /buckets/syncto/collections/(collection_id)/records/(record_id)¶

Example request:

$ http DELETE \
    https://syncto.dev.mozaws.net/v1/buckets/syncto/collections/history/records/d2X1O6-DyeFS \
    Authorization:"BrowserID eyJhbGciOiJSUzI1NiJ9...i_dQ" \
    X-Client-State:64e8bc35e90806f9a67c0ef8fef63...

DELETE /v1/buckets/syncto/collections/history/records/d2X1O6-DyeFS HTTP/1.1
Authorization: BrowserID eyJhbGciOiJSUzI1NiJ9...i_dQ
Host: syncto.dev.mozaws.net
User-Agent: HTTPie/0.9.2
X-Client-State: 64e8bc35e90806f9a67c0ef8fef63...

Example response:

HTTP/1.1 204 No Content
Access-Control-Expose-Headers: Content-Length, Alert, Retry-After, Last-Modified, ETag, Backoff
Content-Length: 0
Date: Tue, 06 Oct 2015 14:18:40 GMT

Status Codes:	204 No Content – The record was deleted 401 Unauthorized – Something went wrong with your authentication 405 Method Not Allowed – This endpoint was not activated in the configuration 412 Precondition Failed – Collection changed since value in If-Match header

Create or Update a record¶

Requires authentication

Create or replace a record with its id. The PUT body is a JSON mapping containing:

• data: the values of the resource schema fields;

Because IDs are created on client side for Firefox Sync, this is the only endpoint that you can use either to create new record or to update them.

If you want to make sure that you don’t erase an existing record when creating one, you can use the If-None-Match: * header value.

The PUT response body is a JSON mapping containing:

• data: the newly created/updated record, if all posted values are valid;

If the request header If-Match is provided, and if the record has changed meanwhile, a 412 Precondition failed error is returned.

There are no validation nor on the id format nor on the payload body.

By default this endpoint is deactivated and should be activated on a per collection basis.

PUT /buckets/syncto/collections/(collection_id)/records/(record_id)¶

Example request:

$ echo '{
     "data": {
         "payload": "{\"ciphertext\":\"75IcW3P4WxUJipehWryevc+ygK5vojh3nOadu7YSX9zJSm3eBHu5lNIg1UtDyt3b\",\"IV\":\"Sj3U2Nkk2IjE2S59hv0m7Q==\",\"hmac\":\"c6a530f3486142d1069f80bfaff907e0cc077a892cf7f9bd62f943b68b610351\"}",
         "sortindex": 2000
     }
 }' | http PUT \
    https://syncto.dev.mozaws.net/v1/buckets/syncto/collections/history/records/d2X1O6-DyeFS \
    Authorization:"BrowserID eyJhbGciOiJSUzI1NiJ9...i_dQ" \
    X-Client-State:64e8bc35e90806f9a67c0ef8fef63...

PUT /v1/buckets/syncto/collections/history/records/d2X1O6-DyeFS HTTP/1.1
Authorization: BrowserID eyJhbGciOiJSUzI1NiJ9...i_dQ
Content-Length: 275
Content-Type: application/json
Host: syncto.dev.mozaws.net
User-Agent: HTTPie/0.9.2
X-Client-State: 64e8bc35e90806f9a67c0ef8fef63...

{
    "data": {
        "payload": "{\"ciphertext\":\"75IcW3P4WxUJipehWryevc+ygK5vojh3nOadu7YSX9zJSm3eBHu5lNIg1UtDyt3b\",\"IV\":\"Sj3U2Nkk2IjE2S59hv0m7Q==\",\"hmac\":\"c6a530f3486142d1069f80bfaff907e0cc077a892cf7f9bd62f943b68b610351\"}",
        "sortindex": 2000
    }
}

Example response:

HTTP/1.1 200 OK
Access-Control-Expose-Headers: Content-Length, Alert, Retry-After, Last-Modified, ETag, Backoff
Connection: keep-alive
Content-Length: 289
Content-Type: application/json; charset=UTF-8
Date: Fri, 09 Oct 2015 10:04:13 GMT
ETag: "1444385059190"
Last-Modified: Fri, 09 Oct 2015 10:04:19 GMT

{
    "data": {
        "id": "d2X1O6-DyeFS",
        "last_modified": 1444385059190,
        "payload": "{\"ciphertext\":\"75IcW3P4WxUJipehWryevc+ygK5vojh3nOadu7YSX9zJSm3eBHu5lNIg1UtDyt3b\",\"IV\":\"Sj3U2Nkk2IjE2S59hv0m7Q==\",\"hmac\":\"c6a530f3486142d1069f80bfaff907e0cc077a892cf7f9bd62f943b68b610351\"}",
        "sortindex": 2000
    }
}

Status Codes:	200 OK – The record was created or updated 400 Bad Request – The request body is invalid 401 Unauthorized – Something went wrong with your authentication 405 Method Not Allowed – This endpoint was not activated in the configuration 412 Precondition Failed – Collection changed since value in If-Match header

GET /¶

The returned value is a JSON mapping containing:

• project_name: the name of the service (e.g. "reading list")

• project_docs: The URL to the service documentation. (this document!)

• project_version: complete application/project version ("3.14.116")

• http_api_version: the MAJOR.MINOR version of the exposed HTTP API ("1.1") defined in configuration.

• cliquet_protocol_version: the cliquet protocol version ("2")

• url: absolute URI (without a trailing slash) of the API (can be used by client to build URIs)

• eos: date of end of support in ISO 8601 format ("yyyy-mm-dd", undefined if unknown)

• settings: a mapping with the values of relevant public settings for clients

  • batch_max_requests: Number of requests that can be made in a batch request.
  • readonly: Only requests with read operations are allowed.

• capabilities: a mapping used by clients to detect optional features of the API.

  • Example:

    {
      "auth-fxa": {
        "description": "Firefox Account authentication",
        "url": "http://github.com/mozilla-services/cliquet-fxa"
      }
    }
    

Optional

• user: A mapping with an id field for the currently connected user id. The field is not present when no Authorization header is provided.

GET /__heartbeat__¶

Return the status of each service the application depends on. The returned value is a JSON mapping containing:

• storage true if storage backend is operational
• cache true if cache backend operational
• permission true if permission backend operational

If cliquet-fxa is installed, an additional key is present:

• oauth true if authentication is operational

Return 200 if the connection with each service is working properly and 503 if something doesn’t work.

GET /__lbheartbeat__¶

Always return 200 with empty body.

Unlike the __heartbeat__ health check endpoint, which return an error when backends and other upstream services are unavailable, this should always return 200.

This endpoint is suitable for a load balancer membership test. It the load balancer cannot obtain a response from this endpoint, it will stop sending traffic to the instance and replace it.

POST /batch¶

Requires authentication

The POST body is a mapping, with the following attributes:

• requests: the list of requests
• defaults: (optional) default requests values in common for all requests

Each request is a JSON mapping, with the following attribute:

• method: HTTP verb
• path: URI
• body: a mapping
• headers: (optional), otherwise take those of batch request

POST /batch HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Content-Length: 728
Host: localhost:8888
User-Agent: HTTPie/0.9.2

{
  "defaults": {
    "method" : "POST",
    "path" : "/articles",
  },
  "requests": [
    {
      "body" : {
        "data" : {
          "title": "MoFo",
          "url" : "http://mozilla.org",
          "added_by": "FxOS",
        },
        "permissions": {
          "read": ["system.Everyone"]
        }
      }
    },
    {
      "body" : {
        "data" : {
          "title": "MoCo",
          "url" : "http://mozilla.com"
          "added_by": "FxOS",
        }
      }
    },
    {
      "method" : "PATCH",
      "path" : "/articles/409",
      "body" : {
        "data" : {
          "read_position" : 3477
        }
      }
      "headers" : {
        "Response-Behavior": "light"
      }
    }
  ]
}

The response body is a list of all responses:

HTTP/1.1 200 OK
Access-Control-Expose-Headers: Retry-After, Content-Length, Alert, Backoff
Content-Length: 1674
Date: Wed, 17 Feb 2016 18:44:39 GMT
Server: waitress

{
  "responses": [
    {
      "status": 201,
      "path" : "/articles",
      "body" : {
        "data" : {
          "id": 411,
          "title": "MoFo",
          "url" : "http://mozilla.org",
          ...
        }
      },
      "headers": {
        ...
      }
    },
    {
      "status": 201,
      "path" : "/articles",
      "body" : {
        "data" : {
          "id": 412,
          "title": "MoCo",
          "url" : "http://mozilla.com",
          ...
        }
      },
      "headers": {
        ...
      }
    },
    {
      "status": 200,
      "path" : "/articles/409",
      "body" : {
        "data" : {
          "id": 409,
          "url": "...",
          ...
          "read_position" : 3477
        }
      },
      "headers": {
        ...
      }
    }
  ]
}

Cache control¶

In order to check that the client version has not changed, a If-None-Match request header can be used. If the response is 304 Not Modified then the cached version is still good.

Concurrency control¶

In order to prevent race conditions, like overwriting changes occured in the interim for example, a If-Match: "timestamp" request header can be used. If the response is 412 Precondition failed then the resource has changed meanwhile.

Concurrency control also allows to make sure a creation won’t overwrite any record using the If-None-Match: * request header.

The following table gives a summary of the expected behaviour of a resource:

When the client receives a 412 Precondition failed, it can then choose to:

• overwrite by repeating the request without concurrency control;
• reconcile the resource by fetching, merging and repeating the request.

Replication¶

In order to replicate the timestamps when importing existing records, it is possible to force the last modified values.

When a record is created (via POST or PUT), the specified timestamp becomes the new collection timestamp if it is in the future (i.e. greater than current one). If it is in the past, the record is created with the timestamp in the past but the collection timestamp is bumped into the future as usual.

When a record is replaced, modified or deleted, if the specified timestamp is less or equal than the existing record, the value is simply ignored and the timestamp is bumped into the future as usual.

See the resource endpoints documentation.

Backoff header on heavy load¶

A Backoff header will be added to the success responses (>=200 and <400) when the server is under heavy load. It provides the client with a number of seconds during which it should avoid doing unnecessary requests.

Backoff: 30

Retry-After indicators¶

A Retry-After header will be added if response is an error (>=500). See more details about error responses.

Protocol description¶

Every response is JSON.

If the HTTP status is not OK (<200 or >=400), the response contains a JSON mapping, with the following attributes:

• code: matches the HTTP status code (e.g 400)
• errno: stable application-level error number (e.g. 109)
• error: string description of error type (e.g. "Bad request")
• message: context information (e.g. "Invalid request parameters")
• info: online resource (e.g. URL to error details)
• details: additional details (e.g. list of validation errors)

Example response

{
    "code": 412,
    "errno": 114,
    "error": "Precondition Failed",
    "message": "Resource was modified meanwhile",
    "info": "https://server/docs/api.html#errors",
}

Refer yourself to the ref:set of errors codes <errors>.

Retry-After indicators¶

A Retry-After header will be added to error responses (>=500), telling the client how many seconds it should wait before trying again.

Retry-After: 30

Precondition errors¶

As detailed in the timestamps section, it is possible to add concurrency control using ETag request headers.

When a concurrency error occurs, a 412 Precondition Failed error response is returned.

Additional information about the record currently stored on the server will be provided in the details field:

{
    "code": 412,
    "errno": 114,
    "error":"Precondition Failed"
    "message": "Resource was modified meanwhile",
    "details": {
        "existing": {
            "last_modified": 1436434441550,
            "id": "00dd028f-16f7-4755-ab0d-e0dc0cb5da92",
            "title": "Original title"
        }
    },
}

Conflict errors¶

When a record violates unicity constraints, a 409 Conflict error response is returned.

Additional information about conflicting record and field name will be provided in the details field.

{
    "code": 409,
    "errno": 122,
    "error": "Conflict",
    "message": "Conflict of field url on record eyjafjallajokull"
    "info": "https://server/docs/api.html#errors",
    "details": {
        "field": "url",
        "record": {
            "id": "eyjafjallajokull",
            "last_modified": 1430140411480,
            "url": "http://mozilla.org"
        }
    }
}

Validation errors¶

When multiple validation errors occur on a request, the first one is presented in the message.

The full list of validation errors is provided in the details field.

{
    "code": 400,
    "errno": 109,
    "error": "Bad Request",
    "message": "Invalid posted data",
    "info": "https://server/docs/api.html#errors",
    "details": [
        {
            "description": "42 is not a string: {'name': ''}",
            "location": "body",
            "name": "name"
        }
    ]
}