One of the best things about Retool is it allows you to connect to any REST API and make it available as a resource. This allows us to easily develop applications using Retool and Fauna, via Fauna’s HTTP API.

Learning Goals

In this tutorial, we’ll walk you through building a basic Todo app in Retool. You will learn how to:

1. Write a “List all Todos” query in Fauna and display it as a table in Retool
2. Write a “Create Todo” query in Fauna and attach it to a form
3. Write a “Update Todo by Id” query in Fauna and attach it to a button
4. In Retool, learn the basics of connecting to resources (e.g. the Fauna HTTP API), assembling UI components, creating and working with resource queries, and attaching them to event handlers.

Prerequisites

• A Fauna account. Sign up or log in via the Fauna Dashboard.
• A Retool account.

Fauna Setup

1. Create a new database

   1. In the Fauna Dashboard, click the [CREATE DATABASE] link in the upper right corner.
   2. Name your database fauna_todo_db (or another name of your choice).
   3. Select a Region Group (e.g. United States (US))
   4. Click the [CREATE] button

2. Create a couple collections

   1. Using the explorer menu on the left, locate the database you created above.
   2. In that database’s Collections panel, click [CREATE COLLECTION] and create a Todo collection.
   3. Repeat the previous step and create a List collection.

3. Add some documents

   The Todo collection is for individual todo items, and the List collection is for categories of todo items. Open up a shell to your database (one should already be open) and enter the following query to add a new List document and several associated Todo documents in one single command:

   let list = List.create({
     title: "Chores"
   })
   list.update({
     todos: [
       Todo.create({completed: false, title: "Walk the dog", list: list}),
       Todo.create({completed: false, title: "Feed the cat", list: list}),
       Todo.create({completed: false, title: "Buy milk", list: list})
     ]  
   })
   

   Run one more query, so that there is more than one item in the List collection:

   let list = List.create({
     title: "Exercise Goals"
   })
   list.update({
     todos: [
       Todo.create({completed: false, title: "Run 5 miles", list: list}),
       Todo.create({completed: false, title: "Swim for 30 minutes", list: list}),
       Todo.create({completed: false, title: "Bike to Fresno and back", list: list})
     ]  
   })
   

4. Create a database access token

   1. Hover over your database in the resource explorer to reveal the Manage Keys button. Click on it to navigate to the Keys view.

      

   2. Click the [CREATE KEY] button.

   3. Leave all the default form inputs.

   4. Provide a name for the key, and click [SAVE]

   5. Your key’s secret is displayed. Copy it to the clipboard (or save it for later use). Secrets are only ever displayed once. If you lose a secret, you have to create a new key.

Create a Retool application

Your Fauna database setup is complete, and now you’re ready to create a user interface for your Todo app. The Retool platform allows you to construct user interface elements which trigger REST API queries to your Fauna database over the HTTP API, so you can add Todo items and mark them completed.

1. Create a new Retool resource

   1. Log in to Retool account. If you’re already logged in, navigate to your account home page by clicking the Retool icon in the upper left corner.
   2. On your Retool account home page, select Resources from the top navigation.
   3. Click the [Create New] > Resource button.
   4. Choose the REST API resource.
   5. Name the resource faunaHttpAPI (or another name of your choice).
   6. For the Base URL, enter **https://db.fauna.com/query/1**
   7. Leave the URL Parameters section blank.
   8. In the Headers section, enter the following keys and values:

   KEY	VALUE	NOTES
   Authorization	Bearer <database access token for your database>	Include your database access token here.
   Accept-Encoding	gzip, deflate, br	Specifies which compression algorithms the client can use.
   Content-Type	application/json	Specifies the media type of the resource.
   Accept	application/json	Specifies which media types the client can use.
   Connection	keep-alive	Specifies a persistent network connection.

   i. Click [Create resource], then [Create an app]

   j. Name your app fauna_todo_app (or another name of your choice).

2. Add a list table showing all items

   

   You should now see the main Retool app development workspace, where you can assemble the components for your Todo app. The first thing you’ll want to do is add a resource query to “List all Todos.” The FQL expression for this is:

   Todo.all() {
   	id,
   	title,
   	completed,
   	category: .list.title
   }
   

   The curly brackets after the main query Todo.all() is called projection, which allows you to specify which fields and in what order they are returned. The cateogry: (with a colon) syntax is field aliasing, which allow you to alias the field name. The Todo document joins to the List document via a reference field list. The syntax .list.title means traverse the field to the List document it references, and return the title field from it. **

   Let’s test this query: From your Fauna dashboard, run the above query in your database’s shell. You should see the following output:

   

   Back in Retool, in your newly created App:

   1. Add the above query as a resource query: Use the code button on the left navigator to open the code list UI.

   2. Click on the plus sign, “+” then “Resource query” to add a resource query. Retool creates a new resource query and defaults it’s name to query1.

      

   3. Rename the resource query to ListAllTodos.

   4. Choose Resource = faunaHttpApi.

   5. Set Action type = POST.

   6. Configure the JSON body to reflect the below**:**

      {
      	query: "Todo.all() {	id,	title,	completed,	category: .list.title}"
      }
      

      (At the time of this writing) For your reference, Retool presents the following UI for configuring steps 3-6, above:

      

   7. Click [Preview] to verify that the response appears as shown below. Notice, it is the same response as you ran the query in the Fauna dashboard, but wrapped in one additional data field. If you see the following, you’ve configured the resource query correctly:

      {
        "data": {
          "data": [
            {
              "id": "375239994636238913",
              "title": "Walk the dog",
              "completed": false,
              "category": "Chores"
            },
            {
              "id": "375239994636239937",
      ...
      

   8. Click [Save]

   9. ⚠️‼️ Click [Run] before the next step.

   10. Drag a Table component into the canvas

       

       Notice that Retool defaulted the component’s name to table1. Leave that as is.

   11. Because you clicked [Run], Retool guesses that you wanted to use the ListAllTodos resource query. It auto-configures the table for you, by setting the Data source to {{ListAllTodos.data.data.data}}, and lists all the query’s projected columns (ID, Title, Completed, Category). You should immediately see the output below: