Bundle references url integration


We are trying to integrate data using the bundle, like:

Loonking for some examples, we can see the use o urls in references, like:

      "fullUrl": "http://example.org/fhir/Patient/23",
      "resource": {
        "resourceType": "Patient",
        "id": "23"
      "fullUrl": "http://example.org/fhir/Observation/124",
      "resource": {
        "resourceType": "Observation",
        "subject": {
          "reference": "http://example.org/fhir/Patient/23"

– Some of these examples showed the url (fullUrl an reference) without the fhir’s version or any other information like http://example.org/fhir/Patient/23, instead of somethinf like these http://example.org/{**other_path**}/fhir/{**r4**}/Patient/23.

Today we have “https://acme.com.br/microservice-fhir-base/r4/fhir/Encounter/107421” and we do not know if we should use something like “https://acme.com.br/fhir/Encounter/107421” in bundle’s reference and/or fullUrl. Can someone help us with this good practice of integration?

Where can we find a documentation about it? We don’t find it easily.


Everything before “/Patient” or “/Encounter” is called the server’s base URL - and it can look like anything you wish. In our examples, we often use “/fhir/” as part of the URL, but that’s not a requirement. Some servers may provide different endpoints for each FHIR release they support, and if so, including the name of the FHIR version in the URL is convenient for readers, but again is not required.

It’s completely fine to have a fullUrl that says “https://201.158.327.57/Patient/123” or even “https://myserver.com/0cc7fec6-a57c-11ed-afa1-0242ac120002/Encounter/abc”.

What your base URL is going to be depends entirely on how you host your site, how many endpoints you have, etc. Ideally they should be human-readable because that’s nicer for implementers, but there are no rules beyond the base rules for URLs generally.

@lloyd I think the main point we would like to clarify is if the fullURL must be a valid url or it serves just as a pointer. In the example cited by @Rodrigo_Lopes, the url contains the string “microservice-fhir-base” because we separate our endpoints in some microservices. But if in the future we decided to change how the microservices are hosted, or simply change the name of them, how should it be treated? We should do some treatment to keep the url the same, as some resources could be already in use for other partners or it could be done and the old resources will have a fullURL that now it’s not valid anymore?

We would like to omit this part in the fullURL in the sake of not compromising with the current structure of our microservices, using “https://acme.com.br/fhir/Encounter/XXX” as fullURL. Is it against the specification?

The fullUrl is expected to be the location you could perform a Read to retrieve the current version of the resource. The only exception is if you’re dealing with a resource that doesn’t have a RESTful endpoint at all, in which case you must use the “urn:uuid:…” approach.

It’s possible that resources get moved, in which case old locations will no longer resolve (though ideally there’d be redirects). What matters is that the location exposed represents the ‘current’ location of the resource.

1 Like