Ryan M. Harrison
Mike Hiner
Amida Technology Solutions, Inc.
December 2021
Summary
The Centers for Medicare and Medicaid Services (CMS) Interoperability and Patient Access Final Rule (CMS-9115-F) requires commercial payers, Medicaid Advantage plans, and state Medicaid agencies to provide a patient access API that will let patients delegate access to their claims and clinical records to third-party applications. This white paper describes the key features of developer portals and emphasizes how they enable third parties to use CMS-mandated APIs “without special effort.”
Conceptual Architecture of a CMS Patient Access API solution
Application developers would use a Medicaid FHIR developer portal to build custom applications for Medicaid members or to integrate Medicaid member data into existing applications. A single portal can serve both first-party and third-party developers; it is not necessary to maintain two distinct portals.1 In Figure 1, we show the developer portal within the context of the major components in a patient access solution.
Landing Page (API Summary)
Developers start here. The landing page contains a marketing description of the API. Where the developer portal serves multiple APIs, the landing page provides a high-level graphical depiction that summarizes the APIs, with links to more detailed marketing pages about each. Some organizations provide separate audience-specific marketing pages, e.g. “Medicaid Administrators,” “Fiscal Agents,” and “Community Developers.”
Quickstart Guide
A guiding principle for modern developer-portal design is “show, don’t tell.” The Quickstart guide shows, in code, a minimum viable example of how to use the API’s core functionality. Links to sample applications that show more complex functionality are often available on public source-control repositories such as GitHub or GNU Savannah. A short sixty- to ninety-second introduction video can serve as a marketing tool, and it can reduce the number of HelpDesk inquiries for the most frequently asked developer questions.2
API Documentation
The API documentation serves as a complete reference for all available endpoints. Common API specification languages, used in the definition of API contracts, include Swagger/OpenAPISpec, RAML, and API Blueprint. API documentation can be generated automatically from these contracts. “Static” documentation only describes API usage, whereas “Live” documentation describes usage and allows the developer to make API requests from within the API documentation. “Live” documentation can be handled by either a mock server (which returns data based on the API specification) or a sandbox environment (which returns synthetic data). API release notes would also appear in this section. Technical marketing and update guidance often accompany major releases — for example, an update from FHIR R4 to R5.
Sandbox Access
Whereas some APIs contain public information and do not require developer registration, FHIR APIs provide access to patient health information;3 therefore, the developer portal must give instructions for application registration. Once registered, the application will be provided credentials that allow the developer to work in a production-like “sandbox” environment populated with sample data. Unlike production access, sandbox access does not require manual review and can be granted automatically.
The benefits of providing sandbox access include: 1) developers build their applications in a SMART on FHIR implementation identical to the production environment, which reduces the risk of access control misconfiguration; 2) the sandbox contains sample data, which lets developers design the application UI using responses similar to those used in the production environment; 3) reduced HelpDesk inquiries, because developers can “self-service” specific usages simply by making requests.
Production Access
Production access is required for state Medicaid members to delegate access to their information. Unregistered applications cannot retrieve member data. Before allowing production access, patient access APIs should apply a vetting process to ensure that applications meet a minimum standard. Data breaches and other negative PR events will reflect poorly on the API owner, even if a third-party application developer is technically at fault.4
In their API Maintenance of Certification criteria, the Office of the National Coordinator for Health Information Technology (ONC) is prescriptive about permitted timelines for application vetting.5,6 Briefly, a certified API Developer has ten days to complete Authenticity Verification, followed by five days for Application Registration. Vetting requirements should include a privacy policy and a data use policy that explain to the Medicaid member – in plain English – how the member’s information will be used, combined, and shared. Naturally, the automation effort applied to vetting should be proportional to the volume of application registrations. At low volume, a wholly manual process is sufficient (e.g., emailing a checklist); at higher volume, semi-automation with a dashboard for application registrants and vetting staff is advisable.
Support
Developer portals often provide links to resources such as source repositories,7 and community forums (e.g., Mastodon communities). Support also includes system status pages to notify the community of outages and production issues, as well as a security contact for reporting security vulnerabilities in the API. Support is the most important fixture of developer community engagement. Responsiveness – including alerts to the developer community about major updates (especially those that break API compatibility) and announcements of security vulnerabilities – builds trust and loyalty over time.8
Budget Gotchas
Build vs Buy
Organizations must budget for both the upfront and the ongoing costs of a developer portal. The most important decision is whether to buy and configure a vendor product (e.g., 3Scale, Apigee, Kong, MuleSoft, Tibco, etc.)9 or build a custom portal.10
Technical Writers
Technical writing is frequently overlooked as an upfront and ongoing cost. An API contract – for example, a Swagger specification – written by engineers and suitable for communication between first-party development teams, will not be sufficient as API documentation for third parties. As the API evolves over time, code changes must be accounted for in the documentation. The need for technical writing waxes and wanes, with peaks around major release dates, but it must be considered until deprecation or end-of-life.
Technical writing is not just a cost center; it can contribute to top-line revenue for monetized APIs. Technical writers can increase API adoption by creating inbound marketing collateral — for example, blog posts that introduce important API features. These materials can highlight the differences between community tiers and paid tiers, and they are invaluable technical marketing collateral.
