Change Practitioner and Organization from Contained Resources to References in FHIR endpoint

[notpace]

Currently, the FHIR API endpoint returns a list of Task resources with either a Practitioner or Organization resource contained within them, depending on the type of Provider Screening Application. This effectively allows implementers to see all the information, but it may not be the best way to model the data, for two reasons:

1. None of the existing FHIR profiling tools (Forge, Trifolia, shr-cli) support constraints on contained resources.
2. Semantically, it makes sense to use contained when the contained resource does not have a unique identifier in the source system. I could be wrong, but I think that Practitioners and Organizations have unique IDs in the PSM database.

I propose that the ID for each Practitioner and Organization resource be returned instead as the focus of each Task. The HAPI-FHIR documentation has information about how to return these resources as references and the FHIR search documentation has information about how to query for Task resources in a way that returns the Practitioner and Organization resources within the bundle.

[notpace]

cc @mbestavros

[jasonaowen]

@dhill has asked this, also, while reviewing PR #670! @cecilia-donnelly kindly answered before I could, but I'd like to expand upon the reasoning behind the current implementation.

At the time, it made more sense to me to have contained resources rather than references for a few reasons. The main reason is that each Practitioner and Organization are unique to the specific enrollment application; they are not reused across multiple enrollment applications. I worried that giving them dedicated resources inaccurately implied behavior about how we store them; I feel like revealing a unique ID suggests that we de-duplicate, and we do not.

Secondarily, given that each Practitioner or Organization is only attached to a single enrollment application, it didn't make sense to me to force the client to make additional requests for data that it couldn't possibly have cached. One advantage of splitting data into separate resources like this is to allow for less redundant data to be transferred, but in this case splitting these resources can't achieve that given the underlying data structure.

Finally, adding more endpoints is both more effort and more of a maintenance burden (an API is like a puppy!), and it also suggests more expansion points, such as search. I didn't want to add more until we had a better understanding of how our users wanted to use the API - which you're providing!

@notpace you have much more context for how this API is being used. Given this context, and in particular given the lack of de-duplication between Practitioners or Organizations involved in applying for multiple enrollments, does splitting these resources out into their own endpoints sound useful to you?

Also, can you say more about this:

None of the existing FHIR profiling tools (Forge, Trifolia, shr-cli) support constraints on contained resources.

What constraints are you wanting to apply, and why?

See also:

• Issue #641 Create API that returns a list of approved and/or rejected providers
• PR #670 Add an API to get a single enrollment application by ID