escribeHOST HAPI FHIR
ESH FHIR Server 1.0

App requirements & registration

App requirements

escribeHOST is a healthcare application that implements the SMART on FHIR standards and specifications, which allow developers to create applications that can securely access and exchange healthcare data using the FHIR (Fast Healthcare Interoperability Resources) standard.

escribeHOST supports both public clients and confidential clients.

• When public clients (e.g., native and single-page applications) request access tokens, some additional security concerns are posed that are not mitigated by the Authorization Code Flow alone. This is because native apps (like android apps) nor single-page-apps (webapps) cannot securely store a Client Secret.
• When confidential clients request access tokens, we use client secret authentication.
• For backend services (apps that run in the background without user interface, for example apps that interacts with bulk export API) we support Asymmetric (public key) authentication compatible with the standard: Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants.

To be considered a client SMART on FHIR app, an application must meet certain requirements.
Some of these requirements include:

• The app must be capable of securely accessing and exchanging healthcare data using the FHIR standard.
• The app must be able to authenticate and authorize users using OAuth 2.0.
• The app must support the SMART on FHIR launch sequence, which allows the app to be launched from within an electronic health record (EHR) system.
  The top level steps required for the client app to launch are presented on the diagram below:
  
• The app must support EHR-level context, which allows it to access relevant patient data and context within the EHR.
• The app must be capable of being installed and uninstalled from an EHR system without causing any disruption to the system or the patient's care.

In addition to these requirements, client SMART on FHIR apps are also expected to follow certain best practices, such as using secure coding techniques and adhering to relevant privacy and security regulations. These requirements and best practices are designed to ensure that SMART on FHIR apps are safe, secure, and interoperable with other healthcare systems.

App registration

Client apps that meet beforementioned criteria, whether they're web apps or native apps, can be registered with escribeHOST.

Client app registration is performed by providing escribeHOST the identity file via secure transport:
SFTP at ftp://lillegroup.com/client-app-registration/post

The client app configuration resides in the same artifact that's provided during registration process.

The identity file should be in JSON format including the following fields:

• appName - Smart on FHIR application name
• audience - target users of app (PATIENTS, CLINICIANS_OR_ADMINISTRATIVE_USERS, BACKEND_SYSTEMS)
• appLaunchUrl - app's launch URL according to SMART App Launch Framework
• appRedirectUris - array of registered redirect URI in OAuth2 flow
• appConfidentialClientSecretHash - in case of providing client secret, sha256 encoded password for the client
• backendServiceJwksUrl - URL of JWKS for backend applications
• summary - summary of the application
• phrPatientScopes - whether the app should be available to all PHR users or limited list (ALL|LIMITED) - applies to PATIENTS only
• requirePKCE - whether PKCE is required for this client
• scopes - array of scopes supported by the application
• limitedPatientIds - array of IDs of patients that app should be available to (just for LIMITED)

Exception handling in escribeHOST HAPI FHIR

Exception handling in escribeHOST HAPI FHIR is similar to exception handling in other types of healthcare applications. escribeHOST HAPI FHIR solution conforms to SMART on FHIR standard. The SMART on FHIR platform provides a number of standard error codes and messages that can be used to indicate the result of a request, such as success or failure.

When an error occurs, the app returns the appropriate error code and message in the response. The error code and message provide information about the specific error that occurred, such as 404 Not Found error code indicating that the requested resource could not be found or 403 that indicates that the entity requesting a resource, although known and identified, cannot perform such a request since it lacks authorization to do so.

Some of the most common exception codes that can be encountered in escribeHOST HAPI FHIR:

• 400 - "invalid request", usually means the request to escribeHOST HAPI FHIR was invalid in some way.
  It could be an invalid type (say, GET not POST), an invalid Content-Type, or perhaps the content itself contains improper (say, out of bounds) data.
  The error response should indicate to the client what's wrong with the request.
• 401 - "unauthenticated", means that the request is performed without prior authentication.
• 403 - "unauthorized", usually means that the party performing the request is known to escribeHOST HAPI FHIR (was authenticated), still it lacks permissions to e.g. requested resource.
• 404 - "not found", means the requested resource does not exist (perhaps it was deleted, or it never existed in the first place).
• 500 - "internal server error", the least likely to be seen. It means something is wrong on escribeHOST HAPI FHIR side. If a retry attempt, best after a couple of minutes, doesn't solve the problem, it makes sense to contact our support.

As the SMART on FHIR stardard in turn conforms and uses HTTP protocol, the full list of possible http status code responses can be found in IANA resources: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml

In addition to returning error codes and messages, escribeHOST HAPI FHIR follows the best practices for error handling. This includes logging errors to help with debugging and troubleshooting and providing user-friendly error messages to help users understand the problem.

Overall, effective error handling is important for ensuring the stability and reliability of SMART on FHIR apps ecosystem. By using standard error codes and following best practices for error handling, developers can create apps that are able to gracefully handle errors and provide a high-quality user experience for patients and providers.