Proprietary APIs Best Practices
Guidelines for implementing and maintaining proprietary APIs that complement standard APIs like FHIR to provide additional functionality and integration options.
While proprietary APIs are not directly regulated by ONC certification criteria, they should follow these best practices to avoid information blocking and ensure interoperability.
Provide comprehensive public documentation
Make API documentation publicly available without requiring registration or NDAs. This should include endpoint descriptions, request/response formats, authentication methods, and error handling.
Include interactive examples
Provide working code examples in multiple programming languages and interactive API explorers that allow developers to test API calls directly from the documentation.
Document versioning and deprecation policies
Clearly communicate API versioning strategy, backward compatibility guarantees, and deprecation timelines to help developers plan for changes.
Provide OpenAPI/Swagger specifications
Offer machine-readable API specifications in standard formats like OpenAPI/Swagger to enable automatic code generation and integration with developer tools.
Implement automated registration
Provide a self-service developer portal that allows immediate registration and access to API credentials without requiring manual approval processes.
Offer sandbox environments
Provide access to sandbox environments with test data that developers can use to build and test integrations without accessing production data.
Transparent approval processes
If production access requires approval, clearly document the criteria, timeline, and process for obtaining approval, with automated status updates throughout the process.
Provide tiered access levels
Implement tiered access levels (e.g., development, testing, production) with appropriate rate limits and capabilities for each tier, with clear paths for upgrading.
Support multi-user organizations
Enable organizations to create and manage multiple user accounts with different roles and permissions for accessing and managing API credentials and applications.
Implement role-based access control
Provide granular role-based access control for API management, allowing organizations to assign specific permissions to different team members based on their responsibilities.
Enable credential rotation
Allow organizations to easily rotate API credentials without disrupting service, supporting security best practices and compliance requirements.
Provide usage analytics
Offer detailed usage analytics and reporting for organizations to monitor API usage, performance, and costs across their applications and users.
Document activation procedures
Provide clear, step-by-step documentation on how healthcare organizations can activate and configure API access within their EHR system, including screenshots and videos.
Specify required permissions
Clearly document the administrative permissions and roles required to activate and manage API access, helping organizations prepare their teams appropriately.
Provide configuration templates
Offer downloadable configuration templates and checklists that healthcare organizations can use to streamline the activation process and ensure all necessary steps are completed.
Document testing procedures
Include procedures for testing API connectivity and functionality after activation, helping organizations verify successful implementation.
Maintain a public API catalog
Publish and maintain a comprehensive catalog of all available APIs, including their purposes, capabilities, and technical specifications, accessible without registration.
Implement API discovery endpoints
Provide machine-readable API discovery endpoints that allow automated tools to discover and understand available APIs and their capabilities.
Document API relationships
Clearly document how proprietary APIs relate to standard APIs like FHIR, including when to use each and how they can be used together for comprehensive solutions.
Provide use case examples
Include detailed use case examples and implementation patterns that demonstrate how different APIs can be combined to solve common healthcare integration challenges.