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

December 3, 2024

Table of Contents

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:

{
  "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:

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, 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.