Fauna Core API
You can use the Fauna Core HTTP API to run FQL queries and subscribe to event streams.
The Fauna client drivers and the Fauna Dashboard use the API to access data in Fauna databases.
This reference documentation describes the endpoints and supported methods for each endpoint.
Endpoints
| Endpoint | Description |
|---|---|
Run an FQL query. |
|
Subscribe to a event stream. |
Base URL
Fauna Core API endpoints use https://db.fauna.com as the base URL.
For example, the full URL for the
/query/1 (Query) endpoint is
https://db.fauna.com/query/1.
Fauna routes requests to a database based on the secret used for authentication. All requests and queries run in the context of a single database.
Authentication
You authenticate requests to Fauna Core API endpoints using an authentication secret. You pass the authentication secret in API requests as a bearer token:
curl -X POST \
'https://db.fauna.com/query/1' \
-H 'Authorization: Bearer <FAUNA_SECRET>' \
-H 'Content-Type: application/json' \
-d '{"query": "Collection.all()"}'Get an authentication secret
Fauna supports several secret types. For testing, you can create a key, which is a type of secret:
-
Log in to the Fauna Dashboard.
-
In the Dashboard, create a database and navigate to it.
-
In the upper left pane of Dashboard’s Explorer page, click the demo database, and click the Keys tab.
-
Click Create Key.
-
Choose a Role of Server.
-
Click Save.
-
Copy the Key Secret. The secret is scoped to the database.
Query API endpoint conventions
This section covers API conventions for the Query API endpoint.
Failed queries
A query can fail because of one of these classes of errors:
| Error classification | Error cause |
|---|---|
Check error |
Before execution, one or more query validation checks failed. |
Runtime error |
An error occurred during query execution. This might include multiple errors and isn’t associated with a particular method. |
Abort error |
An |
Example:
You can see that the response fields are the same as a successful response,
except there is an error field describing the error instead of a data
field, and the summary field includes more descriptive error information.
This error is caused by misspelling the all() method.
{
"error": {
"code": "invalid_function_invocation",
"message": "The function `al` doesn't exist on `Collection`"
},
"summary": "error: The function `al` doesn't exist on `Collection`\nat *query*:1:12\n |\n1 | Collection.al()\n | ^^\n |",
"txn_ts": 1689785459623670,
"stats": {
"compute_ops": 1,
"read_ops": 0,
"write_ops": 0,
"query_time_ms": 0,
"contention_retries": 0,
"storage_bytes_read": 0,
"storage_bytes_write": 0,
"rate_limits_hit": []
},
"schema_version": 0
}Query status
The HTTP status code indicates the request completion status. You should try to first handle the error based on the Fauna error code. If the query returns an error code that isn’t included in the list, handle the error as appropriate for the HTTP status code.
The Query API reference shows the status codes returned by each method.
HTTP status codes are grouped as follows:
| Range | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200-299 |
Successful query
|
||||||||||||
400-499 |
Client error
|
||||||||||||
500-599 |
Server error
|
General status code reference: RFC9110 9110 HTTP Semantics
Value encoding
The Fauna Core API wire protocol data Types representation offers the following benefits:
-
Simplicity The format is easy to read with Fauna as a JSON-only endpoint, which facilitates developing and using drivers.
-
Consistency Ensures complex type information isn’t lost when converting Fauna values to JSON.
These objectives give you a query argument representation format that can be parsed by Fauna, and a response body that can be parsed by clients.
There are two encoding format options:
-
The tagged format includes typing information about every value.
The tagged format can be parsed as input to Fauna. For example, you can write
{ "@date": "2099-12-08" }in JSON using the tagged format, and it is interpreted as a Date. -
The simple format includes FQL literals that can be viewed in the dashboard and CLI. It is a response-only format and can’t be used for query arguments.
Select the value encoding format
You can set the value encoding format in the request header.
Select the format by setting the x-format query header parameter:
| Header | Description | ||||||
|---|---|---|---|---|---|---|---|
|
Request and response format options:
|
Tagged format
Example:
{
"@doc": {
"id": "368117669817221154",
"coll": {
"@mod": "Books"
},
"ts": {
"@time": "2099-06-21T04:53:37.160Z"
},
"name": "Then and Now",
"author": "W. Somerset Maugham",
"data": {
"data": "007571098 "
}
}
}The tagged format has self-describing types. It is intended for drivers that can parse special types, such as Date and Time.
The tagged format is stable, machine-readable, and round-tripable, so you can send response data in the query parameters without making changes.
Parsing
For the tagged format to be used as an input, the Fauna types must be parsed from JSON. The following rules apply to parsing special types:
-
An object that includes a field starting with
@is parsed using the tagged value parser. -
The object needs exactly matching fields to match a given type. If the object includes extra or missing fields, an error is reported with suggested fixes.
-
If the object has exactly matching fields, the values are parsed and result in an error if strings are incorrectly formatted.
The @object notation can be used when you want to declare an object with
fields that include an @ symbol.
These rules also apply to drivers parsing this format.
Disambiguation
To send data that includes @, use the tagged @object value. For example:
{
"not_a_date": {
"@object": {
"@date": "This is parsed as a string",
"some other": "fields"
}
}
}The following example doesn’t have the same effect because the @object tag
affects only the first child:
{
"@object": {
"not_a_date": {
"@date": "This is parsed as a date",
"some other": "fields"
}
}
}This example fails because the object with the @date key has a
"some other": "fields" extra value, which isn’t allowed, and the @date
value is an invalid date.
Simple format
Example:
{
"id": "368117669817221154",
"coll": "Books",
"ts": Time("2099-06-21T04:53:37.160Z"),
"name": "Then and Now",
"author": "W. Somerset Maugham",
"data": {
"data": "007571098 "
}
}With simple format, you can’t tell what the data types are from looking at the
strings. This format is useful when you have a client without a driver.
Typically, clients know the type of their data, so in this example, it is easy
to select and parse the today and now fields.
Format comparison
| Type | Tagged | Simple |
|---|---|---|
(See Number type) |
JSON number |
|
JSON string |
JSON string |
|
JSON array |
JSON array |
|
JSON object |
JSON object |
|
Object with keys prefixed with |
|
JSON object |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Number type
When using the Tagged format, this ensures that data read off the wire has the correct type, independent of the language.
| Type | Tagged format | Simple format |
|---|---|---|
Int (32-bit) |
JSON number |
JSON number |
Long (64-bit) |
|
JSON number |
Double (64-bit float) |
|
JSON number |
Refs
Refs have a type that can be used to reference a document when no data
is read. These are represented with the @ref tag:
{
"@ref": {
"id": "1234",
"coll": {
"@mod": "Foo"
},
}
}You can reference a collection using the <coll>:<id> syntax. For example,
to reference a collection named User, use Collection:User.
If you know the collection, you can paste and return the id value in another
query and use the
collection.byId()
method to get the document.
Is this article helpful?
Tell Fauna how the article can be improved:
Visit Fauna's forums
or email docs@fauna.com
Thank you for your feedback!