Skip to main content

Retool RPC tutorialBeta

A built-in solution to connect your codebase and call server-side functions in Retool apps.

Retool currently supports JavaScript and Python SDKs.

Reach out to your Retool account manager to access Retool RPC on self-hosted Retool 3.38 Edge versions and earlier.

Retool RPC (Remote Procedure Call) is a fast, secure solution for connecting your own codebase to Retool. You define functions in your backend and then call them from Retool apps using a Retool RPC resource.

Prerequisites​

The prerequisites for Retool RPC depend on whether your organization is cloud-hosted or uses a self-hosted deployment.

To start using Retool RPC, you need to:

  1. Create an RPC resource on Retool so Retool apps can communicate with your server.
  2. Generate an access token to authorize your server so it can communicate with Retool.
  3. Register a server with Retool's SDK to expose server-side functions to Retool and to handle function calls.
RPC Architecture

1. Set up Retool RPC​

You can register a server with the Retool CLI or set it up yourself with an existing project and the Retool SDK. The CLI option is recommended for initial testing.

Node.js is required to use the CLI.

The CLI is the easiest way to get started with Retool RPC. It automatically generates a resource and RPC server for you. You can use it to quickly test out Retool RPC and then migrate to a more permanent solution.

To setup Retool RPC with the CLI, run the following commands in your terminal.

# Log into your Retool organization
npx retool-cli login

# Follow the step by step instructions to create a resource and register a server
npx retool-cli rpc

2. Define server-side functions​

After registering your server with Retool, you can interact with your codebase. You need to define functions through your registered server, fill in the implementation, and then call the function from Retool apps.

Be sure to restart your server to pick up any changes to your registered functions.

Retool RPC allows you to customize functions with any number of arguments. Currently supported argument types are: string, number, boolean, json, and array. You can also specify whether an argument is required or optional.

// server.js

rpc.register({
  name: "randomFunction",
  arguments: {
    stringInput: {
      type: "string",
      description: "A required string input",
      required: true,
    },
    numberInput: {
      type: "number",
      description: "A required number input",
      required: true,
    },
    booleanInput: { type: "boolean", description: "An optional boolean input" },
    jsonInput: { type: "json", description: "An optional json input" },
    stringArrayInput: {
      type: "string",
      array: true,
      description: "An optional string array input",
    },
    jsonArrayInput: {
      type: "json",
      array: true,
      description: "An optional json array input",
    },
  },
  implementation: async (args, context) => {
    console.log(args.stringInput);
    console.log(context.userEmail);
    // Use parts of your codebase here
  },
});

The args parameter contains the arguments passed in from Retool, and the context parameter contains information about the user that called the function. Fill in the implementation of the function. Since this server connects to your codebase, you can use your existing infrastructure (ORM frameworks, helper functions, logging, testing, CI/CD, etc.) to enhance the developer experience.

3. Call server-side functions from Retool​

After registering server-side functions, you can call them from Retool apps like any other resource. Search for the RPC resource you created and select the function you want to call. Retool automatically generates a form for you to fill in the arguments.

RPC Query

Enter the arguments and click Run to execute the function. Retool automatically checks the argument passed and displays an error if the types don't match or required fields are missing.

4. Configure function permissions​

You can configure permissions to control access to exposed functions within your organization. Unlike private APIs that require you to build your own authentication middleware, Retool RPC makes it easy to enforce user or group-level access to functions.

rpc.register({
  name: "randomFunctionWithPermissions",
  arguments: {
    stringInput: { type: "string", description: "A string input" },
  },
  permissions: {
    userEmails: ["hello@world.com"],
    groupNames: ["Hello world group"],
  },
  implementation: async (args, context) => {
    return "Hello world!";
  },
});

By default, all functions are accessible to all users. If a userEmails or groupNames field is specified, only users with the specified email or in the specified group can call the function. If both are provided, users only need to satisfy one condition.

RPC Permissions Error

5. Configure schema versioning​

Retool RPC supports schema versioning to ensure exposed functions are always up-to-date. If you check Require explicit version on the resource form, you must increment the version on every server change. This is to ensure non-conflicting changes if multiple people are testing different schemas with the same resource.

Retool RPC Enable Explicit Versioning
const rpc = new RetoolRPC({
  apiToken: 'API_TOKEN',
  host: 'HOST',
  resourceId: 'RESOURCE_ID',
  version: '0.0.1', // Increment this on every server change e.g., 0.0.1 -> 0.0.2 -> 0.0.3
})

If left unchecked, Retool uses the last registered server's schema. This is useful for early development where you want to quickly iterate on your functions.

Retool prompts users to refresh their schema if they are running queries against an outdated schema. This can be done by clicking the refresh button on the Schema tab or by refreshing the page.

Retool RPC Refresh Schema