This is a proposal for a specification, either to remain under the management of Simplifier, or eventually an addition to the FHIR standard, or additional FHIR specification of HL7.
Goal and reason
This specification defines how to connect sites that have FHIR data with sites that can work with that data.
It defines how to use callback URLs for FHIR content from one site to another. We call this the data site and the tool site. It also allows for a third party site, to bridge a data site and a tool site.
Several attempts in the past with a free url format failed. It turned out to be too brittle. This specification makes it more strikt therefore making it easier for both sides to implement and trust no accidental changes will occur.
Working
A site (a) can have a link to a site (b) with a link-query-parameter pointing back to site (a), or possibly a 3rd location. This callback parameter MUST point to a FHIR resource, a fhir endpoint, a package or a file. When a user on site A, clicks on this URL, his browser will browse to that link on site B. Site B will initiate an API call to the callback URL, to retrieve the resource. After that site B, can start working with that resource.
Parameters
There are 4 possible parameters server, resource, file and package.
The value of each of these parameters is a callback URL pointing to an api endpoint. It is up to a tool site to implement either or all of these.
Resource Parameter
The resource URL parameter points to a specific resource on a FHIR server API endpoint.
This allows one site to communicate to the connector site to do something with one specific
FHIR resource.
https://toolsite.net?resource=<url>
Server Parameter
A server callback url points to the root endpoint of a FHIR server. This is for scenarios where the connector page needs to have access to multiple resources. This parameter can be used in combination
with the resource parameter.
If a site is a FHIR Connector page, it has to accept one or more of these parameters, depending on the use case.
https://toolsite.net?server=<url>
File Parameter
A file parameter is a fallback scenario for when a proper FHIR server is not available. It points ot a single downloadable file on an http or https endpoint.
https://toolsite.net?file=<url>
Package parameter
If a fully defined scope must be provided, including dependencies, it might be best to provide a package. This will require for the target site to know how to fetch and install (including restore) a FHIR package. This is assumed for more advanced scenarios, and will probably not be used in most use-cases.
https://toolsite.net?package=<url>
Open Question: Should we provide the full package URL here, or can we assume that the package registry is known, and just provide the package name+version?
FHIR version
It is assumed that the FHIR version in both the source and the target site are known for each particular use-case, either because only one FHIR version is available or by choosing a desginated URL endpoint. So it's not necessary to define in this specification how these sites communicate which FHIR version to use.