GraphQL endpoints

The FaunaDB GraphQL API provides two endpoints:

Endpoint Description

/graphql

Accepts and executes GraphQL queries, and returns the results.

/import

Accepts and imports a GraphQL schema.

These endpoints are hosted at https://graphql.fauna.com/.

/graphql

The /graphql endpoint access GraphQL queries, and returns results in JSON format. See Getting started with GraphQL, or the GraphQL tutorials to see how queries work.

/import

The /import endpoint accepts a GraphQL schema definition, which is translated into the equivalent FaunaDB schema objects.

/import is not for importing data. Use GraphQL mutations to create or update data.

A basic GraphQL schema looks like:

type User {
  username: String!
}

type Query {
  allUsers: [User!]!
}

This query defines a User type, which would become a collection in FaunaDB called User:

Get(Collection("User"))]
{ ref: Collection("User"),
  ts: 1560204122930000,
  history_days: 30,
  name: 'User',
  data:
   { gql:
      { ts: Time("2019-06-10T22:02:02.816944Z"),
        meta:
         { name: 'User',
           fields:
            [ { name: 'username', type: { NotNull: { Named: 'String' } } } ],
           directives: [ { name: 'collection', args: { name: 'User' } } ] } } } }
shell:mydb[

It also defines an allUsers query that provides paginated User results. FaunaDB implements such a query as an index called allUsers:

Get(Index("allUsers"))
{ ref: Index("allUsers"),
  ts: 1560204123110000,
  active: true,
  partitions: 8,
  name: 'allUsers',
  source: Collection("User"),
  data:
   { gql:
      { ts: Time("2019-06-10T22:02:03.010289Z"),
        meta:
         { name: 'allUsers',
           directives: [ { name: 'index', args: { name: 'allUsers' } } ],
           type: { NotNull: { List: { NotNull: { Named: 'User' } } } } } } },
  values: [],
  terms: [],
  unique: false }

For end-to-end examples of importing a schema, creating records, and querying them, see Getting started with GraphQL.

Modes

There are two import modes:

Mode Description

merge

The merge mode creates missing collections, indexes, and functions, and annotates existing FaunaDB schema documents with GraphQL metadata, if required. This is the default mode.

override

The override mode deletes all collections, indexes, and functions that are annotated with GraphQL metadata, pauses 60 seconds to allow all cluster nodes to process the deletions, then it imports the new schema with merge mode.

override mode causes data loss for any previous GraphQL schema. Any collections, indexes, or documents that are not involved in GraphQL are not affected.

Specify the mode using a query parameter. For example:

POST /import?mode=override

If you are using curl, the command would look like:

curl -u <YOUR_FAUNA_SECRET>: https://graphql.fauna.com/import?mode=override --data-binary "@path/to/schema.gql"

Where YOUR_FAUNA_SECRET is a secret associated with the database where the schema should be imported, and path/to/schema.gql is the path to a file containing your GraphQL schema.

Authentication

Both endpoints require authentication with a specific FaunaDB database. This is achieved with a standard FaunaDB secret, which determines the database and permissions to be used.

The secret must be provided as an HTTP Basic Authorization header, encoded as a Base64 string. For example, if your FaunaDB secret is fnADMxRzydATDKibGAciQlNQWBs-HJdpJS1vJaIM, you can encode it like so:

echo -n "fnADMxRzydATDKibGAciQlNQWBs-HJdpJS1vJaIM:" | base64
Zm5BRE14Unp5ZEFUREtpYkdBY2lRbE5RV0JzLUhKZHBKUzF2SmFJTTo=
The trailing colon (:) is required.

Then your Authorization header would look like this:

Authorization: "Basic Zm5BRE14Unp5ZEFUREtpYkdBY2lRbE5RV0JzLUhKZHBKUzF2SmFJTTo="

curl automatically performs the Base64 encoding. Just use the secret as is with the -u flag:

curl -u fnADMxRzydATDKibGAciQlNQWBs-HJdpJS1vJaIM: ...

Errors

Authentication errors result in HTTP 401 error responses, with one of the following messages:

Error message Description

Missing authorization header

The Authorization header was not included in the request.

Invalid authorization header

The value for the Authorization header has an invalid format.

Invalid database secret

The database secret decoded from the Authorization header is not valid.

For the /graphql endpoint, the error message is formatted as JSON:

Status: 200
Content-type: application/json

{
  "errors": [
    { "message": "Invalid database secret." }
  ]
}

For the /import endpoint, the error message is formatted as plain text:

Status: 401
Content-type: text/plain

Invalid database secret.

Next steps

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!