Skip to main content
Version: 0.16.0

Ferry API

Every call is JSON over HTTPS. This section states what holds for every operation, so the operations below describe only what is particular to them.

Authentication and scope​

Send a Keystone token in X-Auth-Token. A project-scoped token acts in its own project: it sees and changes that project's plans, backups and restores and nothing else. Operator calls need a system-scoped token (system: all); each operation names the access it requires.

An operator can act on one project with ?project_id=. ?scope=tenant shows an operator what the project itself sees. It only narrows what an operator sees: a project-scoped token is always answered as its project, whatever it asks for.

Terms​

A backup is called a point in paths and fields: /v1/points, point_id. The prose says backup. A project is the OpenStack project that owns plans, backups and restores.

Errors​

Errors are RFC 7807 problem documents, sent as application/problem+json. code is stable and safe to branch on; it is also the last segment of the type URN. title and detail are prose for people and may change between releases. request_id is the id to quote when reporting a failure; the same value comes back in the X-Request-Id response header. Some problems carry a structured body of their own (fields, refusals, coverage, quota), named on the operations that return them.

Every operation that needs a token can answer 401 unauthenticated. Any operation can answer 500 internal_error or 503 service_unavailable; retry those with backoff. A 503 service_unavailable caused by a service this one depends on not answering in time, such as Keystone while it validates the token, carries a Retry-After header: wait that many seconds before retrying.

Pagination​

Collections return {items, limit, next_marker, total}. limit defaults to 50 and is capped at 500; a larger value is lowered, not refused. To read the next page, send the previous page's next_marker back as marker. next_marker is absent on the last page. A marker is opaque: build none yourself, and expect one to stop working across releases.

Values​

  • Ids are opaque strings. OpenStack resources keep their OpenStack UUIDs.
  • Timestamps are RFC 3339 in UTC.
  • Durations are integers in nanoseconds unless a field says otherwise, for example rpo_target: 86400000000000 is one day.
  • Byte counts are integers in bytes.
  • A measurement the service could not take is absent, never zero. Where it matters the response carries an unavailable map from the field name to the reason it is missing, so "not measured" and "measured as zero" are told apart.
  • Fields marked x-operator-only are returned only to operators; a project-scoped token never sees them.

Authentication​

A Keystone token: scoped to the project the call acts in, or system-scoped for operator calls.

Security Scheme Type:

apiKey

Header parameter name:

X-Auth-Token