...
The best practices and design guidelines are elaborated below.
Design guidelines
Take advantage of the opportunity for caching
Caching - eHealth Infrastructure Wiki - Confluence (atlassian.net)
Make the most of context choices (mainly the careteam context)
...
Design the operation and content of the user interfaces to microservice architecture
Avoid designing a single monolithic User Interface that collects data from many the eHealth microservices into one table or view.
A better option, is to separate different user interfaces and workflows in such a way that there is no need to combine large amounts of data in e.g. the same table view.
Target user interface and workflows to only require data from one (or a few) microservices.
Target the workflows and so that data is only retrieved when they are to be used.
A suggested approach is the use the same microservices strategy to the user interface itself by e.g. introduce micro-apps or micro frontend pattern.
Use of ”Backend for frontend” or API Gateway patterns
API Gateway (or BFF pattern) can be essential, to aggregate multiple downstream calls.
The “API Gateway” pattern can be a useful pattern for the eHealth architectures where there are a small number of backend services.
BFF is a variation of API Gateway pattern and defines a separate API gateway optimized for each kind of client.
...
Using an API gateway has the following benefits:
Isolate the clients from how the application is partitioned into microservices
Isolated the clients from the problem of determining the locations of service instances
Simplifies the client by moving logic for calling multiple services from the client to API gateway
Reduces the number of requests/roundtrips. For example,
The API gateway enables clients to retrieve data from multiple services with a single round-trip. Fewer requests also means less overhead and improves the user experience.
Translates from a “standard” public web-friendly API protocol to whatever protocols are used internally
…
Read more on the API Gateway and BFF pattern here:
Minimize the amount of data that the backend-for-frontend (BFF) has to calculate on
If the vendor application requires a BFF try to minimize the amount of data that the backend-for-frontend (BFF) has to calculate on
Fetching too much and unnecessary data put an extra load on the BFF, and complicates the BFF.
Minimize the amount of data can by done by:
Target user interface design to microservices (see above Design Guide)
Avoid prefetch of data for e.g. details view in a master-detail pattern
Prefer calling eHealth services directly, only use BFF pattern if really needed
Only do caching in vendor application if really needed
…
Avoid unnecessary pre-fetching of data
Under construction
Make the task overview task / message-centric rather than a patient-centric
Under construction
Target the operation (and scope) of the user interfaces to the workflows
Under construction
If you are lucky, you may know enough about what your users will do to next, and thereby be able to prefetch the data they need before it's needed.
Applications (or BFFs) can prefetch the results of a query and placed into the cache
Consider if prefetching is really needed, is the BFF response time better than eHealth services?
Prefetching data may result in the prefetch data is stale, and prefetching too many items increases the load on the eHealth Infrastructure.
Avoid unnecessary auto-updates of the user interface
Under construction
Take advantage of Infrastructure events (mq)
Take advantage of Infrastructure events (mq) for listening to resource changes and perform cache invalidationAutomatic updates of the user interface can be used to avoid users looking on old data.
However, automatic updates of the user interface with updated information on the eHealth Infrastructure should be limited.
Auto updates can be done from the client, by periodically requesting same information from the eHealth Infrastructure, leading to
Automatic updates may require unnecessary processing and polling of data.
Automatic updates may put an extra load on the eHealth infrastructure.
Only do auto update of the user interface if really needed.
And if, preferable use the eHealth domain events, rather than polling for updates.
Take advantage of the opportunity for caching
Caching are both provided by the eHealth Infrastructure that performs server-side caching, but can also be done in Vendor Applications.
...
See https://ehealth-dk.atlassian.net/wiki/spaces/EDTW/pages/1177911316/Caching#Cache-invalidation-using-events for events.
Minimize the amount of data that the backend-for-frontend (BFF) has to calculate on
Under construction
1034354702/Technical+Interactions+with+Services#Caching-on-Searching on caching provided by the infrastructure.
See Caching - eHealth Infrastructure Wiki - Confluence (atlassian.net) for recommendations on caching in the Vendor applications.
Take advantage of the eHealth Infrastructure Event Model
Infrastructure events can be used in Vendor Applications to trigger business functionality.
The eHealth Infrastructure publish simple events at a CRUD resource level e.g.
patient created,
patient updated,
Careplan created,
…
Vendor applications should subscribe to events, instead of polling for changes. Using events is considered more effective than polling for changes.
The events can be used in Vendor Applications to
trigger business functionality in case of events.
Update user interfaces with updated data
update cached information
….
Make effective use of the user selected contexts
Make effective use of the end user selected context and thereby the results returned by the eHealth services
If e.g., the user has set context (patient, episode-of-care, careteam ..) the context can be used to:
Provide as parameter in querying the FHIR services to limit the results, the eHealth services will then filter and limit the results returned to the client.
E.g., only episode of care relevant to selected care-team
•E.g., only tasks relevant to selected care-team
Reduce response times from eHealth services
Minimize data and thereby work in Vendor Applications
Reduce the risk of UTH (adverse events, Danish: utilsigtet hændelse)
Best practices
| Info |
|---|
NOTICE, example URLs in the following are just examples. Please look at the capability statement in the Implementation Guide for the actual capabilities. Furthermore, the infrastructure develops and capabilities may change. |
Optimize call pattern (call in parallel and do not retrieve data one row at a time)
The eHealth infrastructure effectively support parallel requests. If an Application or BFF needs to request data from different services, prefer parallel calls instead of sequential calls if possible.
However, when calling with many concurrent threads from BFFs, it is may be problematic for the infrastructure (similar to DDoS attacks).
Retrieve data on-demand where possible
Best Practice is to generally retrieve data on-demand where possible
That is, first request data when needed.
Avoid prefetch of data for e.g. details view in a Master-Detail pattern
Avoid caching data with the risk of stale data, cache invalidation issues
Limit the number of context changes to what is necessary
In regards to the Design Guides “Make effective use of the selected context” do this with care.
Changing context comes with a penalty. Selecting or changing context results in the user id, access token etc. is refreshed for the specific security context.
Therefore try to limit the number of context changes.
Use the search APIs' counting options to limit the results to the client
The eHealth infrastructure services supports count, to keep the load on clients, servers and the network minimized.
Count are used to limit the number of resources fetched from the database or server.
Example URL to invoke this method:
| Code Block |
|---|
GET [base]/Patient?identifier=urn:foo|123&_count=10 |
See also: http://www.hl7.org/implement/standards/fhir/search.html#count
Take advantage of the opportunity for paging in the Infrastructure
...
That is, eHealth API users only need to request to amount of data that is actually needed, and the limiting of the results can be done at the server or database level.
API users can define a _offset parameter in the request which means that when combined with _count the paging is done on the database level.
(The eHealth infrastructure has a default page size (i.e. default _count if not given) and maximum page size (i.e. maximum value for the _count parameter).
Example URL to invoke this method for the first page (assuming page size of 10):http://fhir.example.com/
| Code Block |
|---|
GET [base]/Patient?identifier=urn:foo|123&_count=10&_offset=0 |
Example URL to invoke this method for the second page:http://fhir.example.com/
| Code Block |
|---|
GET [base]/Patient?identifier=urn:foo|123&_count=10&_offset=10 |
Limit the scope of context changes to what is necessary
Under constructionThe eHealth infrastructure has a default page size (i.e., default _count if not given) and maximum page size (i.e., maximum value for the _count parameter).
Apply filtering to searches
...
to get a smaller and more accurate result
...
Under construction.
Use the search APIs' counting options (Limiting results (_count))
eHealth infrastructure services supports count, to keep the load on clients, servers and the network minimized.
Count may be used to limit the number of resources fetched from the database or server.
Example URL to invoke this method:
http://fhir.example.com/Patient?identifier=urn:foo|123&_count=10
...
Searching for resources is fundamental to the mechanics of FHIR. Generally FHIR use “AND” between the parameters in searching.
FHIR Search _filter _filter is a parameter that can be used with some of the search operations, and provides a powerful language to express filtering restrictions to narrow down the results of a broad query.
It uses the same set of standard parameters defined for the resources, and provides a syntax for expressing a set of query expressions on the underlying resources.
See also:
Use time constraints in searches
...
to get a smaller and more accurate result
A common scenario in searches is to allow searching for resources with values (i.e. timestamps)
...
Under construction
Optimize call pattern (call in parallel and do not retrieve data one row at a time)
Under construction
Retrieve data on-demand where possible
Under constructionwithin a range of dates.
FHIR allows for multiple parameters with the same key, and interprets these as being an AND set. So, for example, a range of &date=gt2022-01-01&date=lt2022-02-01 can be interpreted as any date within January 2022.
Example URL to invoke this method:
| Code Block |
|---|
GET [base]/Appointment?subject.identifier=7000135&start=gt2022-01-01&start=lt2022-02-01 |
The search parameter _lastUpdated can be used to select resources based on the last time they were changed:
| Code Block |
|---|
GET [base]/Appointment?_lastUpdated=gt2022-02-01 |
This search finds any Appointments changed since 1- February 2022.
Careful using chained resource references
FHIR allows reference parameters may be "chained"
The eHealth services has limited support for chained resource references.
FHIR has the concept of chained resource references. That is, references may also support a "chained" value. For example, you might want to search for DiagnosticReport resources by subject, but use the subject's last name instead of their resource ID. In this example, you are chaining "family" (the last name) to "subject" (the patient).
The net result in the query string would look like:
http://fhir.example.com/DiagnosticReport?subject.family=SMITH
What this query says is "fetch me all of the DiagnosticReport resources where the subject (Patient) of the report has the family (name) of 'SMITH'".
Due to the nature of eHealth microservices resources are split into separate services, and therefore limited support for chained resource references, and therefore be careful using theseTo save a client from performing a series of search operations, FHIR allows reference parameters may be "chained" by appending them with a period (.). Example:
| Code Block |
|---|
GET [base]/CarePlan?subject.name=peter |
Return all the careplans that have a subject whose name includes "peter“.
However, due to the eHealth microservice architecture and resources are handled by individual microservices, the chained parameters is only possible with the same service. That is, limited to resources handled by same service.