Api Integration Requirements
Haldis Rucci
Integration Requirement Documents include scope and input documents. They often start with establishing a current evaluation of the business and data system. Then, they will explain the problem the integration is solving for and the business operations affected. As part of this, an assessment of the current data landscape is performed.
The Data Integration Requirements Documents also provide a detailed model for the kind of integration project and architecture that will be performed, something like a blueprint. The data integration model will define what each of the architectural details are and their function. For example, will it be a cloud-based data lake or an in-house data warehouse?
Currently, most application integration is done through REST and SOAP services, which have been determined to meet the majority of the needs on the integration requirements document. Integration requirements have changed, particularly as data management and use has been shaped by a newer, cloud-based utility.
The Bipartisan Budget Act (BBA) of 2018 permanently authorized Medicare Advantage Dual Eligible Special Needs Plans (D-SNPs), strengthened Medicare-Medicaid integration requirements, and directed the establishment of procedures to unify Medicare and Medicaid appeals and grievance procedures to the extent feasible for D-SNPs beginning in 2021. On April 16, 2019, CMS finalized rules to implement these new statutory provisions.
All D-SNPs must have executed contracts with state Medicaid agencies, referred to as the "State Medicaid Agency Contract" (SMAC) or MIPPA contract, that meet a number of requirements, including Medicare-Medicaid integration requirements and, for some D-SNPs, unified appeals and grievance processes.
Each year CMS and states jointly develop state-specific marketing guidance and model member materials for use by Plans. Guidance and model member materials, beginning with the Contract Year (CY) 2025, issued by CMS through the Health Plan Management System (HPMS) for states with Applicable Integrated Plan (AIP) D-SNPs that have chosen to work with CMS on integrated models, appear below. Information is state-specific and alphabetized by state name.
Integrations are hard. By definition, an integration connects two or more systems to enable data exchange. These systems are often using disparate databases, auth, and APIs. And it's common for these systems to be under development also, which means you are trying to hit a moving target.
That said, using well-defined requirements to build integrations can speed time to market for your product's integrations, reduce development, deployment, and support costs, and ensure that end users are pleased with the results.
If we were to start developing an integration based on this requirement, we would end up in an unknown space very quickly. High-level requirements help us define the box, but we need detailed requirements to fill the box. When we refer to requirements for the balance of this post, we are talking about detailed requirements.
Requirements for integrations are often considered unimportant compared to requirements for other software. This thinking about integrations stems from a simplistic understanding: "It just copies data from one system to another. How hard can it be?"
Integrations are much like icebergs. Most of the integration is not visible. So, if we only create requirements for what we can easily see, we'll build something ill-suited to the underlying business need.
Integration requirements are essential to establish an agreed-upon integration scope for all the stakeholders, from engineering to end-users. Yes, even if your devs take an agile approach to integration development, solid requirements make the difference between success and struggle.
The nice thing about gathering requirements for integrations is that we know, at the highest level, what integrations do. This knowledge allows us to narrow the scope of requirements questions from the beginning.
Integrations generally have some type of trigger that causes them to run. These triggers may be event-based (for example, a change in an order record in the CRM) or scheduled (for example, every Thursday at 7:15 AM local time). They may also have manual triggers (if something needs to be forced to run or if the need for data transfer can't be planned programmatically).
A one-way integration sends data from one system to another. A two-way integration sends and receives data. In addition, a single integration could involve three or more systems, each of which could send and/or receive data.
Auth (or authentication) is needed to ensure integrations run securely. Knowing the auth method for each system lets us determine a crucial part of what we'll need to configure for the integration. Systems generally use basic auth, API keys, or OAuth (though other auth types exist). Along with the type of auth, there is the question of whether auth is defined per user or system.
Not all integrations need APIs, but most of them will. Knowing the types of APIs being used gives developers a good idea of the rules and restrictions they'll be working with. REST APIs are used more often than any other type of API, but webhooks (sometimes called reverse APIs) are increasingly common. And some integrations may have an API on one end and a file import/export or something else on the other.
Data transfer is the core of an integration, so getting this right is critical. We often speak loosely about data, using terms like "order data" (going back to our high-level requirement example). Does it mean records from the order table in the sending or receiving system's database (or both)? Does the order data include data from any other tables? If there is conflicting data in the two systems, which one overrides the other?
In many cases, end users look at data on a screen and don't realize that the screen is displaying data from half a dozen database tables. When you specify the data to be transferred, doing so field by field is essential. If "order data" is comprised of 35 fields, explicitly list all those fields.
People use human languages to communicate. Integrations use transport languages to encode the data which is sent between them. XML and JSON are the most common transport languages (also called data exchange formats or data interchange formats), but there are others.
In addition to being encoded in specific languages, integrations also use transfer protocols (a network protocol that supports data transfer between systems). While the APIs often determine these protocols, some systems may provide a choice of protocols.
We touched on translating/mapping between transport languages above, but that's only the start. You may also need to manipulate text strings, perform math calculations, and map data elements from dissimilar schemas. While these are the most common ways to modify data within an integration, this is not an exhaustive list.
To determine needed modifications to integration data, you must compare input data requirements with output data requirements to see what actions the integration must take to transform the input data to match the output data.
Every organization handles requirements gathering differently and expects different roles to contribute. That's fine if you can ensure that you are soliciting requirements information from everyone. And by everyone, we mean everyone who has something to contribute.
To ensure you capture a sufficiently detailed list of requirements, we recommend talking with end users who work with any part of the systems or process with which the integration will interact. If there are users who copy data from System A and place it into System B (and the integration is supposed to replace that manual step), talk with them. Get them to show you precisely what they are doing today and share their expectations of how the integration will change their workflow.
Remember to gather requirements from multiple customers, ensuring you capture the differences between those customers. 95% of the functionality may be identical between customers. But the 5% that is different is critical. Maybe some customers need to include one or more JPG files in the data transfer, while others don't need JPG files at all. Perhaps some customers only need 20 of 25 available data elements, but other customers need all 25.
To productize an integration, you'll need to document the differences (the 5%), decide what is essential to all your customers, and then build a single integration. Inputs and other values that should differ per customer can be set as configuration options, allowing you to build once and deploy many times.
All of these questions come down to not making assumptions, but figuring out what the possible scenarios can be and how you will ensure that your integration can handle them. Sorting these out in the requirements phase will save your team a lot of time and rework during development.
To integrate your SaaS product with a tech partner's app, confirm that you have access to the corresponding API and app (and all available documentation). If you need an NDA with that partner before you and your team can dig into the details, get that done as quickly as possible.
When working with a tech partner, it is common to find that the integration is not as important to them as it is to you. As a result, they lack a sense of urgency and don't see answering your questions or meeting with your team as priorities. You must determine how to make gathering requirements a priority for them or at least come to a shared understanding concerning how quickly and thoroughly they will answer questions so you can plan accordingly.
Asking questions to gather integration requirements can fill that box we mentioned earlier. But what do you do at that point? Do you hand the box over to your development team? Or do you implement an embedded iPaaS to supercharge your integration development, deployment, and support efforts?
Prismatic, the world's most versatile embedded iPaaS, helps B2B SaaS teams launch powerful product integrations up to 8x faster. The industry-leading platform provides a comprehensive toolset so teams can build integrations fast, deploy and support them at scale, and embed them in their products so customers can self-serve. It encompasses both low-code and code-native building experiences, pre-built app connectors, deployment and support tooling, and an embedded integration marketplace. From startups to Fortune 100, B2B SaaS companies across a wide range of verticals and many countries rely on Prismatic to power their integrations.
93ddb68554