Firefox Account OAuth Bearer token¶

Use the OAuth token with this header:

Authorization: Bearer <oauth_token>

$ http GET http://localhost:8000/v0/fxa-oauth/params -v

GET /v0/fxa-oauth/params HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Host: localhost:8000
User-Agent: HTTPie/0.8.0


HTTP/1.1 200 OK
Content-Length: 103
Content-Type: application/json; charset=UTF-8
Date: Thu, 19 Feb 2015 09:28:37 GMT
Server: waitress

{
    "client_id": "89513028159972bc",
    "oauth_uri": "https://oauth-stable.dev.lcip.org",
    "scope": "sync"
}

BrowserID assertion¶

Note that you should also pass the BrowserID assertion to be used with the Firefox Sync Server in the Backend-Authorization header.

GET /history¶

Requires authentication

Returns all records of the current user for this resource.

The returned value is a JSON mapping containing:

• items: the list of records, with exhaustive attributes

A Total-Records header is sent back to indicate the estimated total number of records included in the response.

A header ETag will provide the current timestamp of the collection (see Server timestamps section). It is likely to be used by client to provide If-Modified-Since or If-Unmodified-Since headers in subsequent requests.

POST /batch¶

Requires an FxA OAuth authentication

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

• requests: the list of requests (limited to 25 by default)
• 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

{
  "defaults": {
    "method" : "POST",
    "path" : "/articles",
    "headers" : {
      ...
    }
  },
  "requests": [
    {
      "body" : {
        "title": "MoFo",
        "url" : "http://mozilla.org",
        "added_by": "FxOS",
      }
    },
    {
      "body" : {
        "title": "MoCo",
        "url" : "http://mozilla.com"
        "added_by": "FxOS",
      }
    },
    {
      "method" : "PATCH",
      "path" : "/history/409",
      "body" : {
        "read_position" : 3477
      }
    }
  ]
]

The response body is a list of all responses:

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

GET /¶

The returned value is a JSON mapping containing:

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

• version: complete version ("X.Y.Z")

• commit: the HEAD git revision number when run from a git repository.

• 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)

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

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

  • cliquet.batch_max_requests: Number of requests that can be made in a batch request.

• userid: The connected perso user id. The field is not present when no Authorization header is provided.

GET /__heartbeat__¶

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

• cache true if operational
• sync true if operational

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

Versionning¶

The API versioning is based on the application version deployed. It follows semver.

During development the server will be 0.X.X, the server endpoint will be prefixed by /v0.

Each non retro-compatible API change will imply the major version number to be incremented.

Everything will be made to avoid retro incompatible changes.

The / endpoint will redirect to the last API version.

Deprecation¶

A track of the client version will be kept to know after which date each old version can be shutdown.

The date of the end of support is provided in the API root URL (e.g. /v0)

Using the Alert response header, the server can communicate any potential warning messages, information, or other alerts.

The value is JSON mapping with the following attributes:

• code: one of the strings "soft-eol" or "hard-eol";
• message: a human-readable message (optional);
• url: a URL at which more information is available (optional).

A 410 Gone error response can be returned if the client version is too old, or the service had been remplaced with a new and better service using a new protocol version.

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 to error responses (>=500), telling the client how many seconds it should wait before trying again.

Retry-After: 30

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: additional details (e.g. URL to error details)

Example response

{
    "code": 400,
    "errno": 109,
    "error": "Bad Request",
    "message": "Invalid posted data",
    "info": "https://server/docs/api.html#errors"
}

Error codes¶

Validation errors¶

In case multiple validation errors occur on a request, they will be returned one at a time.