An overview of First Dollar’s API offering and documentation.
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:
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.
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.
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:
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.
“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.
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.
From the get-go, we built our platform with APIs. APIs power First Dollar's web applications, mobile applications, embeddable SDKs, and are publicly available for current and potential partners to explore. Offering an API-first solution enables our partners to have more control and directly build featured experiences in their existing products.
- Mike DeWitt, Chief Technology Officer at First Dollar
Our public APIs give us and our partners a ton of tangible benefits, including:
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.
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:
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.
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.
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:
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.
With our APIs, you can:
We also offer the following products for our partners:
Check the documentation out for yourself at developer.firstdollar.com.
