Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now GA.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

Migrating from v3 of the CLI? See the CLI migration guide.

Explore Fauna HTTP APIs with Postman

Postman is a popular tool for testing and debugging HTTP APIs.

This guide covers how you can use Postman with the Fauna HTTP APIs, including how to make API requests and generate code samples.

Postman offers both a web app and a desktop app. This guide focuses on the web app, but the steps are similar for the desktop app.

Before you start

To use Postman with the Fauna HTTP APIs, you need the following:

Fork a Fauna HTTP API collection

Postman organizes API endpoints into collections, which are stored in workspaces. When you create a Postman account, Postman creates a personal workspace for you. By default, this workspace is visible only to you.

The Fauna HTTP APIs workspace is a public workspace that publishes collections for:

The collections in this workspace are managed by Fauna and are visible to anyone.

To use a collection from the Fauna HTTP APIs workspace, you must fork the collection. Forking saves a copy of the collection to another workspace. This lets you:

  • Send HTTP API requests using endpoints in the collection. You can’t send requests from the public workspace.

  • Make changes to the collection, such as configuring authorization or variables, without affecting the public version.

Use the Run in Postman button

The HTTP API reference docs include a Run in Postman button. You can use this button to fork a collection for the respective API.

  1. On the Core HTTP API reference or Account HTTP API reference docs page, click the Run in Postman button.

    Run in Postman button

    This opens a Postman page containing a Fork collection into your workspace modal.

    Fork collection into your workspace modal

  2. Click Fork Collection.

    If prompted, sign in to Postman.

  3. On the Fork Collection page, enter a Fork label and select a workspace.

    Run in Postman button

  4. Click Fork Collection.

    The collection appears in the sidebar of the workspace you selected.

    Workspace sidebar

Sync a forked collection

Fauna regularly updates the collections in the Fauna HTTP APIs workspace. These updates can include documentation for new functionality, bug fixes, and the removal of deprecated features.

You can sync your collection to pull updates into your fork.

  1. In Postman’s left sidebar, click the more actions icon (...) next to the collection name.

  2. Click Pull changes.

  3. Review the changes and click Pull changes to update your collection.

Configure a collection

After forking the collection, you need to configure it to include your authentication token.

The Fauna HTTP APIs use bearer tokens for authentication. The value of this token varies based on the API.

API Accepted bearer token

Core API

Authentication secret

Account API

Account API key

Before making API requests with Postman, you’ll need to set the bearerToken variable in the collection.

The bearerToken variable’s value is visible to anyone with access to your Postman workspace. You should treat bearer tokens as passwords.

  1. In Postman’s left sidebar, click the collection name.

  2. Click the Variables tab.

  3. In the Variables tab, add a new variable with the following field values:

    • Variable: bearerToken

    • Initial value: Your bearer token’s value

    • Current value: Your bearer token’s value (auto-filled)

  4. Click Save.

    Set bearer token variable

Make an API request

After configuring your forked collection, you can use Postman to send API requests using the collection’s endpoints.

  1. In Postman’s left sidebar, click the collection name and navigate to the endpoint you want to use. Then click the endpoint name.

  2. Click the Params tab.

    If needed, select and specify path or query parameters for the request. You can view supported values in the corresponding section of the HTTP API reference.

    Set bearer token variable

  3. Click the Body tab.

    If needed, specify a JSON body for the request. You can view supported properties in the corresponding section of the HTTP API reference.

  4. Click Send to make the request.

    A response appears in the bottom pane.

    Response in Postman pane

Generate sample code

Fauna provides official client drivers in several programming languages for the Core API.

For languages without a client driver, or when working with the Account API, you can use Postman to generate sample code that interacts directly with Fauna HTTP API endpoints.

To generate sample code using Postman:

  1. In Postman’s left sidebar, click the collection name and navigate to the endpoint you want to use. Then click the endpoint name.

  2. Click the Params tab.

    If needed, select and specify path or query parameters for the request. You can view supported values in the corresponding section of the HTTP API reference.

    Set bearer token variable

  3. Click the Body tab.

    If needed, specify a JSON body for the request. You can view supported properties in the corresponding section of the HTTP API reference.

  4. Click the Code icon. Then select your preferred programming language or framework.

    Postman automatically generates a code snippet. You can copy and paste the snippet into your app.

    Generate code sample

Import Fauna OpenAPI specifications into Postman

Fauna updates collections in the Fauna HTTP APIs workspace based on OpenAPI specifications.

You can download the OpenAPI specifications from the following documentation pages:

Run in Postman button

If you prefer, you can import the OpenAPI specifications directly into Postman. This is functionally equivalent to forking the related collection from the Fauna HTTP APIs workspace.

For instructions, see Import an API into Postman in the Postman docs.

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!