<!-- LLM_VERSION_INFO
FORMAT: text/markdown
CONTENT_TYPE: article
ORIGINAL_URL: https://www.tryfinch.com/blog/building-finchs-api-explorer-from-openapi-spec-to-interactive-tool
ALTERNATE_VERSION: blog/building-finchs-api-explorer-from-openapi-spec-to-interactive-tool.html (text/html)
EXTRACTION_DATE: 2026-04-18T21:48:55.938Z

This is the markdown version with text-only content (images converted to alt-text).
For rich formatting with images, request the HTML version at: blog/building-finchs-api-explorer-from-openapi-spec-to-interactive-tool.html
-->

# Building Finch's API Explorer: From OpenAPI Spec to Interactive Tool

December 3, 2024

## Table of Contents

- [Finch's API Explorer Features](/content/blog/building-finchs-api-explorer-from-openapi-spec-to-interactive-tool#finchs-api-explorer-features/index.html)
- [1. Democratized API access](/content/blog/building-finchs-api-explorer-from-openapi-spec-to-interactive-tool#1-democratized-api-access/index.html)
- [2. Seamless authentication and access control](/content/blog/building-finchs-api-explorer-from-openapi-spec-to-interactive-tool#2-seamless-authentication-and-access-control/index.html)
- [3. Real-time API specification sync](/content/blog/building-finchs-api-explorer-from-openapi-spec-to-interactive-tool#3-real-time-api-specification-sync/index.html)
- [4. User-friendly JSON builder](/content/blog/building-finchs-api-explorer-from-openapi-spec-to-interactive-tool#4-user-friendly-json-builder/index.html)
- [5. Context-aware operations](/content/blog/building-finchs-api-explorer-from-openapi-spec-to-interactive-tool#5-context-aware-operations/index.html)

## Introducing the Finch API Explorer

The Finch API Explorer is a new interactive tool that allows developers to interact with our API endpoints directly from the Developer Dashboard. This tool is especially important in the employment space, where testing different scenarios with pay and organization data is essential to a successful integration.

What began as an internal tool to accelerate our own development operations has evolved into a powerful feature for our external developers.

.png)

## **Finch's API Explorer Features**

### **1. Democratized API access**

The API Explorer democratizes access to our API by removing traditional technical barriers. Team members across different roles can make API requests directly from the Developer Dashboard without the need for access tokens. This is particularly valuable for sandbox environments, where teams can easily test and validate their integration without additional setup.

### **2. Seamless authentication and access control**

Our API Explorer is integrated with the Finch developer Dashboard, eliminating the need for manual access token management. We've implemented role-based access controls to ensure the right level of access for different users. Every request made through the Explorer is recorded in the activity tab, making it easy to track and audit API usage.

### **3. Real-time API specification sync**

The Explorer is dynamically generated from our OpenAPI specification, ensuring it's always in sync with our latest API changes. This automatic synchronization means developers always have access to the most current API interface.

### **4. User-friendly JSON builder**

Our JSON builder translates the OpenAPI specification into an intuitive form interface. Here’s how the builder transforms complex JSON into an intuitive interface:

**Example JSON Code:**
```typescript
{
  "legal_name": "New legal name",
  "entity": {
    "type": "corporation",
    "subtype": "c_corporation"
  },
  "primary_email": "new@email.com",
  "primary_phone_number": "1234567890",
  "ein": "23456",
  "locations": [
    {
      "line1": "Line 1",
      "line2": "Line 2",
      "city": "City",
      "state": "State",
      "postal_code": "12345",
      "country": "US"
    }
  ],
  "accounts": [
    {
      "routing_number": "12345",
      "account_name": "12345",
      "institution_name": "12345",
      "account_type": "checking",
      "account_number": "2345"
    }
  ]
}
```

### **5. Context-aware operations**

A unique feature of the API Explorer is its contextual awareness. When a sandbox app is selected, the Explorer dynamically adds sandbox-specific endpoints to the list of operations.

## **Tackling technical challenges**

Creating a robust API Explorer has its challenges. Here are some key areas where we had to innovate:

### **1. Parsing and understanding our OpenAPI specification**

The first challenge was parsing our OpenAPI specification. One key challenge was resolving **$ref** pointers in the OpenAPI spec. Here’s a solution:

```typescript
const resolveRef = (ref: string, spec?: OpenAPIV3.Document) => {
  const [, ...pathToSchema] = ref.split('/');
  return _.get(spec, pathToSchema, {});
};
```

### **2. Creating the JSON builder**

Using React and [react-hook-form](https://react-hook-form.com/), we developed a recursive component that dynamically renders form fields based on the schema.

### **3. Request proxying and security**

Our approach includes schema validation, request logging, CORS protection, and role-based access control. This ensures secure access to API operations.

### **4. Optimizing performance**

We implemented several optimizations to ensure the API Explorer remains responsive, including lazy loading of operation details and debounced validation for form inputs.

## **Future enhancements**

We're exploring ways to enhance our API Explorer, including a request recording feature and smarter field population based on previous API calls.

## **Develop with Finch**

Building the API Explorer has empowered both our internal teams and external developers to interact with our API seamlessly. As we continue to refine the API Explorer, we look forward to making API integration even easier for our users.