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

We’re pleased to announce the Finch API Explorer: a new interactive tool that allows developers to interact with our API endpoints directly from the 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. Keep reading to explore the benefits of the API Explorer in greater detail. 

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 now make API requests directly from the developer Dashboard without the need for access tokens or using external tools like cURL or Postman:

• Non-engineering team members can validate data formats without developer assistance.
• Support teams can quickly reproduce and debug customer issues.
• Sales engineers can demonstrate API capabilities in real-time.
• Quality assurance teams can test various data scenarios efficiently.

Whether testing a deduction request or checking company data, any authorized user can interact with the API through an intuitive interface. 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 deeply integrated with the Finch developer Dashboard, eliminating the need for manual access token management. When developers log into the dashboard, they can immediately start making API calls — no additional authentication required. We've also implemented role-based access control, ensuring that only admin users can access the Explorer, providing an extra layer of security. 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. When we add new endpoints, update parameters, or modify response schemas, these changes are immediately reflected in the Explorer. This automatic synchronization means developers always have access to the most current API interface without requiring any updates to their tooling.

4. User-friendly JSON builder

One of our key goals was to make API interaction accessible to developers of all technical levels. Our JSON builder translates the OpenAPI specification into an intuitive form interface:

• Field types and validations are automatically enforced based on the schema.
• Dropdown menus are populated with enumerated values from the spec.
• Complex nested objects and arrays can be built with simple clicks.
• Real-time validation ensures requests are properly formatted before sending.

Here's how the builder transforms complex JSON into an intuitive interface:

And here is the resulting 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 in the developer Dashboard, the Explorer dynamically adds sandbox-specific endpoints to the list of operations, providing clarity and precision for developers.

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. While there are existing tools like @apidevtools/swagger-parser, we opted for a simpler, custom solution that gave us more control over the parsing process.

One key challenge was resolving $ref pointers in the OpenAPI spec. These references allow schema definitions to be reused across the specification, but they need to be resolved first. Here's our straightforward solution:

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

This simple function handles resolution of references by following the path specified in the $ref pointer. The callers of this function also handle the recursive resolution of nested $ref pointers. While more complex solutions exist, this approach proved sufficient for our needs and kept our dependency footprint small.

2. Creating the JSON builder

The JSON Builder posed unique challenges, particularly in handling nested objects, arrays, and schema validations. Using React and react-hook-form, we developed a recursive component that dynamically renders form fields based on the schema. Here’s how it works:

• Dynamic Input Types: Adjusts inputs for strings, numbers, booleans, enums, and more
• Array Support: Adds or removes array elements dynamically
• Nested Object Handling: Renders subfields for complex objects
• Schema Switching: Allows toggling between multiple schema types when applicable

Here's a snippet of the JSON Builder implementation:

export const JsonBuilder = ({
  jsonSchemas,
  propertyKey,
  formPath,
  deleteField,
}: {
  jsonSchemas: JsonSchemaSelections;
  propertyKey?: string;
  formPath: string;
  deleteField?: () => void;
}) => {
  const { register } = useFormContext();
  const [schema, setSchema] = useState(jsonSchemas[0]);

  return (
    <FieldContainer
      propertyKey={propertyKey}
      formPath={formPath}
      deleteField={deleteField}
      setSchema={setSchema}
      selectedSchema={schema}
      schemas={jsonSchemas}
    >
      {schema.type === 'object' ? (
        <Stack>
          {Object.entries(schema.properties).map(([key, value]) => (
            <JsonBuilder
              key={key}
              jsonSchemas={value}
              propertyKey={key}
              formPath={`${formPath}.${key}`}
            />
          ))}
        </Stack>
      ) : schema.type === 'array' ? (
        <ArrayInput propertyKey={propertyKey} formPath={formPath} schema={schema} />
      ) : (
        <Input {...register(formPath)} />
      )}
    </FieldContainer>
  );
};

3. Request proxying and security

Security was a top priority when implementing the request proxy. Our approach includes:

1. Schema Validation: Each request is validated against the OpenAPI spec to ensure only valid operations are allowed.
2. Request Logging: All requests are logged alongside the authenticated user for audit purposes.
3. CORS Protection: The proxy endpoint only accepts requests from our developer dashboard domain, preventing unauthorized access from external sources.
4. Role-Based Access Control: Only users with admin role and appropriate permissions can make proxy requests, ensuring controlled access to API operations.

This multi-layered security approach ensures that the API Explorer remains both powerful and secure, giving access only to authorized users while maintaining a comprehensive audit trail of all operations.

4. Optimizing performance

We implemented several optimizations to ensure the API Explorer remains responsive:

• Lazy loading of operation details
• Memorization of resolved references
• Debounced validation for form inputs
• Progressive loading of large response data

Future enhancements

We're thrilled to see how developers will leverage the API Explorer feature to streamline their integration processes and explore the full capabilities of the Finch API.

Provider requests recording

The internal version of the API Explorer includes a powerful request recording feature, capturing all external requests made during the lifecycle of a Finch API call. This provides invaluable insights into how Finch interacts with various payroll and HRIS, making debugging and optimization much more efficient. We're exploring ways to make this feature generally available to all Finch users in the future.

Smarter field population

We're developing intelligent field pre-filling based on previous API calls. For example:

• Using the /employer/directory endpoint responses to populate individual ID dropdowns for /employer/individual, /employer/employment, and /employer/benefits/{benefit_id}/individuals endpoints
• Preserving frequently used field values across operations

UI refinements

We're continuously working to simplify the interface while maintaining its power:

• Collapsible sections for large request bodies
• Better visualization of nested array structures
• More intuitive handling of complex objects
• Improved error message displays with actionable fixes

Develop with Finch

Building the API Explorer has been a transformative journey for Finch, empowering both our internal teams and external developers to interact with our API seamlessly. By leveraging the OpenAPI spec and thoughtful design, we’ve created a tool that democratizes access to API development while maintaining high security and usability standards.

As we continue to refine the API Explorer, we look forward to making API integration even easier for our users. Stay tuned for updates!

Not a Finch developer yet? Contact our Sales team to learn how we can help you integrate with more than 200 HRIS and payroll systems, or try our API yourself.