01 Documentation

Languages:

Introduction

The REST API provides straight-forward, resource-based access to FaunaDB. Any resource with a ref is available at its corresponding path.

Schema Endpoints

The endpoints /databases, /keys, /classes, and /indexes allow the creation of schema instances and pagination through existing instances.

GET /<schema class ref>

Get a list of existing schema instances.

Parameters
ts Integer optional Return the set at the specified point in time.
after Cursor optional Return the next page of results after this cursor (inclusive).
before Cursor optional Return the previous page of results before this cursor (exclusive).
size Integer default 16 Maximum number of results to return.

The pagination cursor may be one of:

  • A URL-escaped JSON value.
  • A ref string without the { "@ref": ... } container.

Equivalent Query


{ "paginate": <schema class ref>, ... }

POST /<schema class ref>

Create an instance of a schema class.

POST accepts a JSON object via the request body. See the corresponding schema type in the Object Reference for a list of valid parameters.

Equivalent Query


{ "create": <schema class ref>, "params": { "quote": <body params> } }

The endpoints /databases/<name>, /keys/<id>, /classes/<name>, /indexes/<name> allow the retrieval and modification of instances of schema classes.

GET /<schema instance ref>

Get a schema instance.

Query Parameters
ts Integer optional Return the instance at the specified point in time.

Equivalent Query


{ "get": <schema instance ref> }

PUT /<schema instance ref>

Replace a schema instance’s data.

PUT accepts a JSON object via the request body. See the corresponding schema type in the Object Reference for a list of valid parameters.

Equivalent Query


{ "replace": <schema instance ref>, "params": { "quote": <body params> } }

PATCH /<schema instance ref>

Update a schema instance.

PATCH accepts a JSON object via the request body. See the corresponding schema type in the Object Reference for a list of valid parameters.

Equivalent Query


{ "update": <schema instance ref>, "params": { "quote": <body params> } }

DELETE /<schema instance ref>

Delete a schema instance. See the corresponding schema type in the Object Reference for information on the effects of deletion.

Equivalent Query


{ "delete": <schema instance ref> }

GET /<schema instance ref>/events

Get a schema instance’s event history.

Parameters
ts Integer optional Return the set at the specified point in time.
after Cursor optional Return the next page of results after this cursor (inclusive).
before Cursor optional Return the previous page of results before this cursor (exclusive).
size Integer default 16 Maximum number of results to return.

The pagination cursor may be one of:

  • A URL-escaped JSON event
  • A timestamp

Equivalent Query


{ "paginate": <schema instance ref>, "events": true }

Instance Endpoints

The endpoint /classes/<name> allows the creation of instances of the corresponding class.

POST /<class ref>

Create an instance of a class.

POST accepts a JSON object via the request body.

Equivalent Query


{ "create": <class ref>, "params": { "quote": <body params> } }

The endpoint /classes/<name>/<id> allows the retrieval and modification of instances.

GET /<instance ref>

Get an instance.

Query Parameters
ts Integer optional Return the instance at the specified point in time.

Equivalent Query


{ "get": <instance ref> }

PUT /<instance ref>

Replace an instance’s data.

PUT accepts a JSON object via the request body.

Equivalent Query


{ "replace": <instance ref>, "params": { "quote": <body params> } }

PATCH /<instance ref>

Update an instance.

PATCH accepts a JSON object via the request body.

Equivalent Query


{ "update": <instance ref>, "params": { "quote": <body params> } }

DELETE /<instance ref>

Delete an instance.

Equivalent Query


{ "delete": <instance ref> }

GET /<instance ref>/events

Get an instance’s event history.

Parameters
ts Integer optional Return the set at the specified point in time.
after Cursor optional Return the next page of results after this cursor (inclusive).
before Cursor optional Return the previous page of results before this cursor (exclusive).
size Integer default 16 Maximum number of results to return.

The pagination cursor may be one of:

  • A URL-escaped JSON event
  • A timestamp

Equivalent Query


{ "paginate": <instance ref>, "events": true }

Other Endpoints

GET /ping

Check service health. For a given scope, a successful ping means the following:

  • node: the responding node is available.
  • local: the local datacenter is available.
  • global: the global cluster is available.
  • all: all nodes in the cluster are available.

The default scope is global.

Responds with 200 OK on success, 503 on timeout, or 500 if a data inconsistency is detected.

Parameters
scope String optional One of node, local, global, or all.
timeout Integer optional Time to wait for the ping to succeed, in milliseconds.