# How to Integrate Retool with IntelliJ IDEA

- Tool: Retool
- Difficulty: Intermediate
- Time required: 45 minutes
- Last updated: April 2026

## TL;DR

Use IntelliJ IDEA with Retool by developing JVM-based backend services (Java, Kotlin, Python) in IntelliJ that Retool connects to via REST API Resources. IntelliJ handles backend service development, API design, and debugging while Retool consumes the resulting APIs. This development workflow is ideal for teams building Java Spring Boot or Kotlin backends that power Retool internal tool dashboards.

## Build Backend APIs in IntelliJ IDEA for Retool Integration

Many organizations using Retool have existing or planned JVM-based backend services built with Java, Kotlin, or Scala. These services often contain business logic, data transformation, or access patterns that are not exposed through the raw databases and third-party APIs that Retool typically connects to directly. When you need Retool to trigger complex business processes — running a payment reconciliation job, invoking an order fulfillment workflow, or querying a data service that aggregates multiple internal systems — a dedicated backend API service developed in IntelliJ is the right approach.

The IntelliJ-Retool workflow is straightforward: backend engineers design and build REST endpoints in IntelliJ using Spring Boot, Micronaut, or other JVM frameworks, test them using IntelliJ's built-in HTTP Client tool, and then configure Retool REST API Resources pointing to the deployed endpoints. Retool operators then build dashboards that call these endpoints without needing to understand the underlying Java code. This separation of concerns — IntelliJ engineers handle business logic, Retool operators handle UI — is a productive model for teams with mixed technical skill sets.

IntelliJ's tooling for this workflow is mature: the HTTP Client plugin allows testing API endpoints in .http files that live alongside the code, Spring Boot run configurations enable live reload for local development, and the built-in database tools can be configured to connect to the same databases that Retool queries directly — allowing side-by-side comparison of what the API returns vs. what the raw data looks like.

## Before you start

- IntelliJ IDEA (Community or Ultimate) installed with a Java 11+ or Kotlin SDK configured
- A JVM-based web framework set up: Spring Boot (recommended), Micronaut, Quarkus, or similar
- A Retool account with permission to create REST API Resources
- Understanding of REST API design principles and HTTP methods
- Basic knowledge of JSON response formatting and HTTP status codes

## Step-by-step guide

### 1. Set up an IntelliJ Spring Boot project for Retool-facing APIs

Start or open an IntelliJ project with a JVM web framework. For a new Spring Boot project, use IntelliJ's built-in Spring Initializr integration: File → New → Project → Spring Initializr. Select Java or Kotlin, add dependencies: Spring Web (for REST endpoints), Spring Boot Actuator (for health checks Retool can monitor), and your data access layer (Spring Data JPA, JDBC Template, or MongoDB). When designing controllers for Retool consumption, follow these API design principles that optimize for Retool's data binding: return JSON arrays at the top level for list endpoints (Retool's Table component expects arrays, not nested objects), include pagination metadata as top-level fields alongside the data array ({ 'data': [...], 'total': 100, 'page': 1, 'pageSize': 25 }), use consistent snake_case field names (Retool transformers handle camelCase but snake_case is more readable in SQL-heavy environments), and return meaningful error responses with consistent error field names ({ 'error': true, 'message': '...', 'code': 'VALIDATION_ERROR' }). Configure CORS in your Spring Boot application to allow requests from Retool's proxy IP ranges for local testing, or configure your deployment to accept requests from Retool Cloud's CIDR blocks. For local development with a locally-running Retool instance, configure CORS to allow http://localhost:3000.

```
// Spring Boot REST controller optimized for Retool consumption
// Example: Java Spring Boot endpoint returning Retool-friendly paginated response

@RestController
@RequestMapping("/api")
@CrossOrigin(origins = "*")  // Restrict to Retool IPs in production
public class OrderController {

    @Autowired
    private OrderService orderService;

    @GetMapping("/orders")
    public Map<String, Object> getOrders(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "25") int pageSize,
        @RequestParam(required = false) String status,
        @RequestParam(required = false) String startDate,
        @RequestParam(required = false) String endDate
    ) {
        Page<Order> orders = orderService.findOrders(
            status, startDate, endDate,
            PageRequest.of(page, pageSize)
        );

        Map<String, Object> response = new HashMap<>();
        response.put("data", orders.getContent());
        response.put("total", orders.getTotalElements());
        response.put("page", page);
        response.put("page_size", pageSize);
        return response;
    }
}
```

**Expected result:** A Spring Boot application runs in IntelliJ with REST endpoints returning JSON responses in a Retool-friendly format.

### 2. Use IntelliJ HTTP Client to design and test API endpoints

IntelliJ IDEA includes a built-in HTTP Client that allows testing REST endpoints using .http files. This is particularly useful for validating the exact request/response format that Retool will use before configuring it in Retool's query editor. To create an HTTP Client file, right-click your project → New → HTTP Request File (or create a file with the .http extension in IntelliJ Ultimate, or use the scratch file feature). Write test requests in the HTTP Client format. Include test cases that mirror what Retool will send: requests with URL parameters for filtering and pagination, POST requests with JSON bodies for create/update operations, and requests with Authorization headers for secured endpoints. Run each request with the green Run button next to the request. IntelliJ displays the response status, headers, and body. Copy the response shape and use it when building Retool transformers — you want to know exactly what JSON structure your transformer needs to handle before writing it. The HTTP Client also supports environment files (.http.env.json) for switching between local, staging, and production base URLs — this mirrors the multi-environment pattern you will use in Retool's Configuration Variables.

```
### List orders with filters (Retool will send similar requests)
GET http://localhost:8080/api/orders
  ?page=0
  &pageSize=25
  &status=processing
  &startDate=2024-01-01
  &endDate=2024-12-31
Authorization: Bearer {{auth_token}}

### Create a new order comment
POST http://localhost:8080/api/orders/{{order_id}}/comments
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "comment": "Processing delayed due to inventory check",
  "notify_customer": false,
  "author": "ops-team"
}

### Health check (Retool can monitor this)
GET http://localhost:8080/actuator/health
```

**Expected result:** HTTP Client test requests return expected JSON responses, validating the API contract before configuring Retool Resource queries.

### 3. Configure a Retool REST API Resource for your IntelliJ service

With the API working and tested in IntelliJ, configure a Retool REST API Resource to connect to the deployed service. Deploy your Spring Boot application (to staging/production via your CI/CD pipeline, or use ngrok for local testing with Retool Cloud). Navigate to Retool Resources → Add Resource → REST API. Name it after your service (e.g., 'Orders Service API'). Set the Base URL to your deployed service URL (e.g., https://orders-api.yourcompany.com). Configure authentication — if your service uses Bearer token auth, select Bearer Token and reference the token from a Configuration Variable: {{ retoolContext.configVars.ORDERS_SERVICE_TOKEN }}. If using API key auth, add the key as a header. Add any required default headers your service needs. Click Save Changes. Build queries in a Retool app that mirror the HTTP Client tests you wrote in IntelliJ: a GET query with URL parameters for filtering, POST queries for mutations. The response format you validated in IntelliJ's HTTP Client should match exactly what Retool receives, making transformer development straightforward. For local development testing, use ngrok (ngrok http 8080) to expose your local IntelliJ-running service to Retool Cloud temporarily — this enables building Retool apps against a live development API without deploying to staging.

**Expected result:** A Retool REST API Resource connects to the deployed IntelliJ-developed service, and test queries return the same response format seen in IntelliJ's HTTP Client.

### 4. Debug Retool query issues using IntelliJ's debugger

When Retool queries return unexpected results or errors from your IntelliJ-developed service, IntelliJ's debugger is the primary tool for investigation. Set breakpoints in your Spring Boot controller or service layer at the method entry points for the endpoints Retool calls. In IntelliJ, switch from Run to Debug mode: click the Debug button (green bug icon) instead of the Run button for your Spring Boot run configuration. With the service running in Debug mode, trigger the failing Retool query in your Retool app. IntelliJ will pause execution at your breakpoints, allowing you to inspect the exact request parameters received from Retool (HttpServletRequest object), the intermediate processing states, the database query being executed, and the final response being serialized. Common debugging scenarios: Retool passes numeric pagination parameters as strings (page='1' instead of page=1) — inspect the raw parameter type in IntelliJ to add proper type coercion. Retool's {{ }} expressions evaluate to null in some states — add null checks in your Spring controller. Date parameters formatted by Retool's Date Range Picker may not match your service's expected format — inspect the raw date string parameter and add flexible parsing. Use IntelliJ's Evaluate Expression (Alt+F8) at breakpoints to test fixes without restarting the server.

```
// Example: Spring Boot controller with debug-friendly logging
// Add this to your controller to log incoming Retool requests

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@GetMapping("/orders")
public Map<String, Object> getOrders(
    HttpServletRequest request,
    @RequestParam Map<String, String> allParams
) {
    // Log all received parameters for debugging Retool query issues
    log.debug("Retool query received - params: {}", allParams);
    log.debug("Request URI: {}, Remote addr: {}",
        request.getRequestURI(), request.getRemoteAddr());

    // Defensive parameter handling for Retool's dynamic expressions
    int page = parseInt(allParams.getOrDefault("page", "0"));
    int pageSize = Math.min(parseInt(allParams.getOrDefault(
        "pageSize", "25")), 100); // Enforce max page size

    // ... rest of implementation
}
```

**Expected result:** IntelliJ debugger successfully catches Retool-triggered requests at breakpoints, allowing inspection of request parameters and service behavior for rapid issue resolution.

### 5. Design API responses for optimal Retool component binding

The API response shape from your IntelliJ service directly determines how easy or complex the Retool transformer and component configuration will be. Following these design guidelines reduces the JavaScript transformer code you need to write in Retool. For list endpoints: return a flat array at the top level or as data field — { 'data': [...], 'total': 100 }. Avoid deeply nested structures. Each array item should have an 'id' field (Retool Tables use this for row identification). For date fields: return ISO 8601 strings (2024-01-15T10:30:00Z) so Retool can format them with new Date().toLocaleString(). For money fields: return raw numbers (cents or decimal), not pre-formatted strings — format in Retool transformers for flexibility. For enum/status fields: return consistent lowercase strings ('pending', 'processing', 'complete') for predictable conditional formatting. For pagination: return total_count and current_page to drive Retool's Pagination component without client-side calculation. For error responses: return HTTP 4xx/5xx status codes (not 200 with error flags) so Retool's query failure handlers trigger correctly. Document this API contract in your IntelliJ project's README or OpenAPI spec so Retool app builders know the expected response format. For complex integrations involving custom API layer design, multi-service aggregation patterns, and Retool-optimized response schemas, RapidDev's team can help architect your backend service design for Retool consumption.

```
// Kotlin data class for Retool-optimized API response
// Returns structure that works directly with Retool Table component

data class RetoolPagedResponse<T>(
    val data: List<T>,           // Array at 'data' key for Table binding
    val total: Long,             // Total count for Pagination component
    val page: Int,               // Current page (0-indexed)
    val page_size: Int,          // Items per page
    val has_more: Boolean = data.size >= page_size
)

data class OrderSummary(
    val id: Long,                // Required for Retool Table row identification
    val order_number: String,    // snake_case for SQL-native feel
    val status: String,          // Lowercase enum: 'pending', 'processing'
    val customer_email: String,
    val total_cents: Long,       // Raw cents, format in Retool transformer
    val created_at: String,      // ISO 8601 string
    val item_count: Int
)
```

**Expected result:** API responses from the IntelliJ-developed service require minimal transformer code in Retool and bind cleanly to Table, Form, and Chart components with predictable field names.

## Best practices

- Design Spring Boot endpoints specifically for Retool consumption: flat JSON arrays for list endpoints, consistent snake_case field names, and explicit pagination metadata (total_count, page, page_size) to drive Retool Pagination components
- Use IntelliJ's built-in HTTP Client to write .http test files that document the exact request format Retool will use — commit these to the repository as living API documentation for Retool app builders
- Return proper HTTP status codes (4xx/5xx for errors, not 200 with error flags) so Retool's query failure handlers and event handlers trigger correctly for error scenarios
- Add Spring Boot Actuator health endpoints to every Retool-facing service — create a Retool monitoring query that checks /actuator/health to provide early warning when a dependent service goes down
- Use ngrok for testing Retool Cloud against locally-running IntelliJ services during development — this avoids the overhead of deploying to staging for every API change
- Configure request logging in Spring Boot controllers at DEBUG level to capture all incoming Retool request parameters, making it easy to reproduce issues when Retool queries produce unexpected behavior
- Import your service's OpenAPI/Swagger spec into the Retool REST API Resource — this provides endpoint path autocomplete for Retool app builders who are not IntelliJ backend engineers

## Use cases

### Build a business logic API layer for Retool to call from a Java Spring Boot service

Develop a Spring Boot REST API in IntelliJ that exposes complex business operations as simple HTTP endpoints — for example, an order reconciliation endpoint that queries multiple internal services, applies business rules, and returns a unified report. Retool calls this endpoint with a single query, letting operators trigger complex backend workflows from a simple UI without exposing raw database access.

Prompt example:

```
Build a Retool dashboard that calls a Spring Boot /api/reconcile-orders endpoint (developed in IntelliJ). The endpoint accepts a date range and returns reconciliation discrepancies. Display results in a Retool Table with export-to-CSV capability.
```

### Develop a gRPC service in IntelliJ with a REST gateway for Retool

Build a gRPC service in IntelliJ (Java/Kotlin) and expose it via a REST gateway (Spring Cloud Gateway or Envoy) that Retool can query as a REST API Resource. Use IntelliJ's gRPC support for service development and testing while providing Retool a standard HTTP interface for building management dashboards on top of gRPC-based microservices.

Prompt example:

```
Build a Retool panel that queries a gRPC service's REST gateway to list active jobs, trigger new jobs, and display job execution status — all backed by a Kotlin gRPC service developed and tested in IntelliJ.
```

### Build a Kotlin data aggregation API that combines multiple internal service responses for Retool

Develop a Kotlin backend in IntelliJ that aggregates data from multiple internal microservices (database, message queue status, external APIs) into a single response optimized for Retool's display format. Retool calls this aggregation endpoint instead of needing multiple parallel queries and client-side joining, simplifying the Retool app and reducing the number of API calls.

Prompt example:

```
Build a Retool operations dashboard that calls a single Kotlin aggregation API endpoint (developed in IntelliJ) returning combined order, inventory, and shipping status data. The API handles all internal service calls, and Retool only makes one query to display the complete operations view.
```

## Troubleshooting

### Retool queries return CORS errors when connecting to the locally-running IntelliJ Spring Boot service

Cause: CORS (Cross-Origin Resource Sharing) errors occur when testing Retool against a local service, even though Retool's standard Resource Queries proxy server-side. CORS errors appear in local development when using Retool's self-hosted version or when using JavaScript query fetch() calls that execute client-side instead of through the proxy.

Solution: For Retool Cloud querying a local service: use ngrok (ngrok http 8080) to expose your local service with a public HTTPS URL, then configure the Retool resource with the ngrok URL. For self-hosted Retool querying localhost: configure CORS in Spring Boot to allow requests from your Retool instance origin. Standard Retool REST API Resource queries always use the server-side proxy and should not generate CORS errors — if you see CORS errors, you may be using a JavaScript query with fetch() instead of a Resource Query.

```
// Spring Boot CORS configuration for Retool development
@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
            .allowedOrigins(
                "https://your-retool-instance.com",
                "http://localhost:3000" // self-hosted Retool local dev
            )
            .allowedMethods("GET", "POST", "PUT", "DELETE", "PATCH")
            .allowedHeaders("*")
            .allowCredentials(true);
    }
}
```

### Spring Boot service returns 401 Unauthorized when Retool tries to connect, but the same request works in IntelliJ HTTP Client

Cause: The Retool REST API Resource may not be correctly passing the authentication header. If authentication is configured in the resource but the header name does not match what the Spring Boot service expects (e.g., the service expects 'X-API-Key' but Retool sends 'Authorization'), the service rejects the request.

Solution: Add request logging to the Spring Boot controller (or use Spring's CommonsRequestLoggingFilter) to log all incoming headers from Retool requests. Compare the logged headers against what the IntelliJ HTTP Client sends. In the Retool resource configuration, verify the exact header name and format match your service's authentication filter expectations. Check that the token value in Retool's Configuration Variable does not have leading/trailing whitespace.

### Retool pagination does not work correctly — always loads the same data regardless of page

Cause: The Spring Boot service may be returning 0-indexed pages while Retool's Pagination component is 1-indexed, or vice versa. If Retool passes page=1 but the service expects 0-indexed pagination, the service always returns the second page.

Solution: In IntelliJ, check your controller's @RequestParam default value and processing for the page parameter. Spring Boot's Pageable convention uses 0-indexed pages. If Retool sends page starting at 1, subtract 1 in the controller or in the Retool query URL parameter expression: {{ (pagination.page || 1) - 1 }}. Log the received page value in IntelliJ's debugger to confirm what Retool is sending.

## Frequently asked questions

### Does IntelliJ IDEA have a direct integration with Retool?

No, there is no direct plugin or built-in integration between IntelliJ IDEA and Retool. The integration is a development workflow: IntelliJ developers build backend services (Java/Kotlin Spring Boot, Micronaut, etc.) that Retool connects to as REST API Resources. IntelliJ is used for service development and debugging while Retool handles the UI layer and queries the resulting APIs.

### Can I use IntelliJ to build Retool Custom Components?

Retool Custom Components are React-based, and while IntelliJ IDEA supports JavaScript and TypeScript, VS Code with its richer JavaScript tooling ecosystem is more commonly used for Custom Component development. IntelliJ Ultimate includes JavaScript and TypeScript support that is sufficient for Custom Component work, but the IntelliJ-Retool workflow is primarily valuable for JVM backend service development rather than frontend Custom Component building.

### How do I expose a locally-running IntelliJ service to Retool Cloud for testing?

Use ngrok (ngrok.com) — run 'ngrok http 8080' in a terminal to create a public HTTPS URL that tunnels to your localhost:8080 Spring Boot service. Configure a Retool REST API Resource with the ngrok URL for testing. This allows building Retool dashboards against your local IntelliJ service without deploying to staging. Note that ngrok URLs change each session on the free plan — update the Retool resource URL when starting a new ngrok session.

### What Spring Boot features are most useful for building Retool-facing APIs?

Spring Boot Actuator for health check endpoints, Spring Data REST for automatic CRUD API generation from JPA repositories, SpringDoc OpenAPI for automatic API documentation importable into Retool, and Spring Boot DevTools for hot reload during development. The @CrossOrigin annotation controls CORS for development, and @ControllerAdvice handles global exception formatting to ensure consistent error response shapes across all Retool-facing endpoints.

---

Source: https://www.rapidevelopers.com/retool-integrations/intellij-idea
© RapidDev — https://www.rapidevelopers.com/retool-integrations/intellij-idea