The existence of a cell phone would ruin many movie plots. The McCallister family wakes up to their iPhone alarms,* Casey Becker identifies who's talking on the other end via caller ID, and Bueller's parents (as well as everyone else in Chicago) see the trending hashtag #SaveFerris. A direct line of communication helps you get things done—even if it doesn't make for a great plot.
Application programming interfaces (APIs) enable technology solutions to talk directly with each other. For administrators that provide health spending benefits like flexible spending and health savings accounts, an API solution offers:
- The ability to own the customer experience (e.g., HSA solution on their portal)
- Improved efficiency (e.g., admins teams empowered to solve customer issues on their platform)
- Improved products (e.g., more intuitive experiences for customers)
In this post, our Lead Engineer, Nathan Chapman, will share why First Dollar's engineering team built an API solution, how we document** our APIs, and how an API solution can help solve pain points for benefits administration.
*And Kevin can call his parents
**If you’d like to look at our API documentation, check out our developer docs here.
The challenge for healthcare and banking data
RBC Capital Markets reports, "The healthcare industry is generating 30% of the world's data volume. Benefits enrollment, account holder spending, issuing a virtual card, processing funding, and cardholders signing in to their mobile app are examples of real-life data for platforms administering benefits. So how is that data shared with multiple solutions? For many today, the answer is "Could be better."
The digitalization of healthcare and banking data dates back as far as the 1960s. With the age and heavy regulation of many of these institutions, come systems and processes that can feel outdated, hard to scale, and limited in the capabilities that they provide to integrators. Many of these systems are so prolific that they have also permeated into newer “healthtech” and “fintech” companies. Interactions between these systems often involve transferring files over secure networks, known as SFTP, typically either manually or on a set schedule. When these files are exchanged, they have to be transferred in a usable format for the consumer.
Flat file exchanges
Healthcare and banking institutions often use positional flat files, where records have a fixed length and each field has an explicit start and end character position. This format gained popularity in the 1980s and has stuck around, even though CSV, XML, and JSON have been adopted for intercompany data transfer in many other sectors. You may be thinking this sounds pretty brittle, and you’d be right. Fields may end up truncated, position rules are different for each file you may be receiving or transferring, and ordering of fields is incredibly important.
Flat files typically each serve a singular purpose. One flat file may provide user enrollment data, while another may provide transaction data. Each file needs to follow a specific naming convention, so they can be parsed and processed by the appropriate handler.
Evolving these formats over time is challenging and requires:
- Tight collaboration between integrators
- Versioning file formats
- Rewriting existing file parsers / generators (likely on both sides of the integration)
When dealing with this file-based approach, we not only have to handle recording the state of already-processed files, but approach fault tolerance in a “batch” manner. What if only part of a file was successfully processed? Treating the entire file as an error state would mean data would be lost, while re-processing the entire file could result in duplicate operations. Many times these issues have to be manually remediated.
Another issue is scheduling. The ideal time to process these files for one partner may be drastically different for other partners. What if specific files should be processed in the morning and others at the end of the day? Running a “daily” or “nightly” job wouldn’t cover all scenarios for our partners.
A note on First Dollar and file exchanges
“API or files?” is one of the first questions we ask potential partners. We’ve built the file exchange process for our partners and will continue to maintain it. There’s no perfect solution (e.g., bank integration requires flat file-based exchanges), and sometimes the file exchange process is the most straightforward approach for a partner. Yes, file exchanges have challenges, but we’re committed to meeting the needs of all benefits administrators. The goal of this blog post is not to disparage file exchanges, but to highlight how helpful APIs can be for embedded benefits.
To alleviate many of these challenges, we’ve built what we call FDX, or our “Flexible Data Exchange.” FDX is a JSON-based file exchange protocol that uses JSON schemas to validate both the structure and contents of files. When integrating with a new partner, we give them the option to choose between flat file exchanges, FDX, or our APIs.
Why we built APIs
Unfortunately, a platform provider can't flip a switch and have an API-first platform. It takes intentional decisions from engineering leadership and follow-through with prioritization on the product roadmap.
Our public APIs give us and our partners a ton of tangible benefits, including:
- On-demand execution
- Immediate feedback loop
- A job completion notification system, and
- A strong, evolvable contract
With the on-demand nature of an API, a partner can call our APIs at the most opportune moment, rather than uploading files to an SFTP server and waiting for them to get picked up and processed. For example, this means that users could be enrolled in benefits and issued a virtual card immediately, if desired, and see transactions on their Health Wallet in near real-time.
Partners also get an immediate HTTP response from our API endpoints. This means they’ll know whether or not an operation was valid and processed as soon as they make a request to our API, rather than only getting a notification (e.g., an email or slack notification) at some later point when processing completes. This removes a layer of human intervention, where an engineer or manager may have to check in over email or Slack to ask if files have started processing and what the status is.
Even with APIs, some operations may take much longer to complete. In these cases, we still immediately respond with a job ID that partners can use to check the status of a given job. We’re planning on building webhook support in the near future, which will enable partners to subscribe to event notifications.
Using an API instead of a file exchange enables greater flexibility in the capabilities we can offer over time. For example, it allows us to add additional information to response objects or allow different types of inputs for lookup or modification. With APIs, we can make these changes without breaking the integrating partner’s parsers, like we would in a flat file scenario. This desire for highly flexible endpoints with strong guarantees led us to use GraphQL for our API technology.
Why we chose GraphQL
Several prominent architectural styles exist for building APIs. While Representational State Transfer (REST) has been the de facto standard for many years, GraphQL offers significantly more flexibility and stronger guarantees than traditional API technologies like REST and SOAP (Simple Object Access Protocol). GraphQL solves a lot of problems found in those other API technologies, because it:
- Supports fetching all of the data you need in a single request, using graph relationships
- Moves the concept of “views” from the server to the client
- Supports schema additions without affecting existing client calls
- Allows batching queries to fulfill all of the data requirements of a page in a single request
- Simplifies operations into just two categories: fetching data (Queries) and modifying data (Mutations)
- Supports introspection, meaning the server can tell you exactly what its capabilities are
- Provides an excellent developer experience for viewing the schema and building queries
- Performs query validation at both run-time and build-time
- Guarantees the shape of the response object will match a valid query shape specified by the client
- Removes the concept of versioning from the API while still supporting evolution
- … and more!
GraphQL is served over HTTP (just like REST) and uses JSON as the encoding for exchanging data. This means that existing HTTP request tooling and libraries will work great, but using ones with GraphQL support will improve the developer experience.
Our REST API
While we primarily focus on developing our APIs using GraphQL, we do have a REST API for partners who would prefer to use REST over GraphQL. Our REST API is generated directly from our GraphQL API using SOFA.
How we document our APIs
One of the great things about GraphQL is its approach to documentation. It supports both documentation and code comments for each field in the schema. This means we can have internal-facing comments for things like TODOs and external-facing comments for descriptions, guidance on usage, etc. Even better, this documentation is co-located with the schema definition, which means it’s easier to maintain and more likely to reflect what’s currently deployed. This makes documentation part of our normal development process, rather than an afterthought.
Through GraphQL’s introspection support, we’re able to:
- Automatically generate an API reference from our schema that includes these documentation comments
- Provide an API Explorer for crafting queries and viewing the documentation in an interactive way
What our API documentation looks like
From the consumer experience to the administrative workflows and core bank functions, every function in our platform has an API—but you don't have to take our word for it. Here are the three main ways that you can review our documentation on our developer portal:
API Overview: Your engineering team’s go-to guide for understanding how we set up our API and how you interact with it. The API Overview includes breakdowns of our environments, authentication strategies, how to use our API Explorer (see below), pagination strategies, how we handle breaking changes, and our changelog.
API Reference: Browse our documentation organized by function and type. You'll find queries, mutations, objects, interfaces, enums, unions, inputs, scalars, and directives here. And thanks to GraphQL, we automatically generate API references from our schema, ensuring our documentation matches deployed code.
GraphQL API Explorer: Explore our GraphQL schema and test queries and mutations against our Sandbox environment. This is a very interactive way to view our documentation and receive real-time feedback.
Our platform’s capabilities
With our APIs, you can:
- Build health benefits directly into your existing application
- Administer benefits programs that can include benefits like HSAs, FSAs, Directed Spend, Rewards, and more
- Manage organizations and their benefits programs
- Manage benefits within programs
- Manage individuals and their enrollments
- Issue virtual and physical cards
- View account balances and transactions
- … and more!
We also offer the following products for our partners:
- The Health Wallet app for individuals to access their benefits
- The Health Wallet Manager app for benefits administration
- Embeddable Widgets to integrate into your existing applications
Seeing is believing: Check out our API
Check the documentation out for yourself at developer.firstdollar.com.
