GraphQL endpoints

The FaunaDB GraphQL API provides two endpoints:

Endpoint Description

https://graphql.fauna.com/graphql

Accepts and executes GraphQL queries, and returns the results.

https://graphql.fauna.com/import

Accepts and imports a GraphQL schema.

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

GraphQL queries are executed by sending HTTP requests to the https://graphql.fauna.com/graphql endpoint. This documentation does not describe how to implement HTTP requests, as you can do so in many different languages. Common GraphQL HTTP request information is available here: https://graphql.org/learn/serving-over-http/

https://graphql.fauna.com/graphql

The https://graphql.fauna.com/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.

https://graphql.fauna.com/import

The https://graphql.fauna.com/import endpoint accepts a GraphQL schema definition, which is translated into the equivalent FaunaDB schema objects.

The https://graphql.fauna.com/import endpoint is not for importing data, it is for importing a schema only. 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.

The purpose of override mode is to make it easy to experiment with varying schemas. During development of your schema, it is often easier to start with a fresh schema.

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 -H 'Authorization: Bearer <FAUNA_SECRET>' https://{hostname}/import?mode=override --data-binary "@path/to/schema.gql"

Where 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 can be provided through the HTTP Authentication request header, either as a Bearer token, or via HTTP Basic authentication.

Bearer token

To use the FaunaDB secret as a Bearer token, the Authorization header should look like:

Authorization: Bearer <secret>

For example, if your FaunaDB secret is fnADMxRzydATDKibGAciQlNQWBs-HJdpJS1vJaIM, then your Authorization header would look like:

Authorization: Bearer fnADMxRzydATDKibGAciQlNQWBs-HJdpJS1vJaIM

If you are using curl, you can specify the Authorization header like so:

curl -H 'Authorization: Bearer fnADMxRzydATDKibGAciQlNQWBs-HJdpJS1vJaIM' ...

HTTP Basic

To use the FaunaDB secret with HTTP Basic authentication, provide the secret as the username value. You do not need to provide a password. Make sure that you encode the credentials into a Base64 string. For example, if your FaunaDB secret is fnADMxRzydATDKibGAciQlNQWBs-HJdpJS1vJaIM, you can convert it to HTTP Basic credentials like so:

echo -n "fnADMxRzydATDKibGAciQlNQWBs-HJdpJS1vJaIM:" | base64
Zm5BRE14Unp5ZEFUREtpYkdBY2lRbE5RV0JzLUhKZHBKUzF2SmFJTTo=
The trailing colon (:) is required as it separates the username and password values.

Then your Authorization header would look like:

Authorization: Basic Zm5BRE14Unp5ZEFUREtpYkdBY2lRbE5RV0JzLUhKZHBKUzF2SmFJTTo=

curl automatically performs the Base64 encoding. Use the -u flag and specify the secret with a trailing colon:

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!