ncbi / dbgap-fhir-api-docs

The documentation repository for the dbGaP FHIR API.

DbGaP FHIR API Docs

This is the documentation repository for the dbGaP FHIR API. (API base URL)

dbGaP is the Database of Genotypes and Phenotypes.
FHIR is HL7's REST API standard for transmission of electronic health record data.

• Quickstart
• Obtaining a Task-Specific Token for Controlled Data
• Notebooks

Prerequisites

You should already have a basic understanding of FHIR - especially before working through the Notebooks. The notebooks are based on the FHIR Exercises repo from the NIH Office of Data Sharing Strategy (ODSS).

For the Notebooks, you should also understand how Notebooks work and Pandas dataframes.

Issues

If you have a query that returns after 20 seconds with an error like the following:

{
	"error": {
		"status": 500,
		"message": "error forwarding request",
		"api-key": "192.168.0.1"
	}
}

Then you probably hit a 20-second timeout. Removing sorting, simplifying your query, or including fewer sub-queries in a batch can sometimes help.

For other issues please see the Issues list in this GitHub repository.

Privacy

The example code in this repository does not collect user data or send it to NCBI. However, using the code to access our FHIR servers will send data to NCBI. To learn more about how we handle that data, see the "NCBI Website and Data Usage Policies and Disclaimers" page.

Contact

The dbGaP FHIR API is provided by NCBI. Please contact us with any questions.

dbGaP FHIR is under active development; suggestions for features and data are welcome.

dbgap-fhir-api-docs's Issues

x1 links in quickstart.md do not work

http://dbgap-api.ncbi.nlm.nih.gov/fhir/x1 is given but produces 400 bad request.

Update readme

Update readme for NCPI project use.

Queries not listed in CapabilityStatement may give unpredictable results

Our server may respond to a query that is not listed as supported in the CapabilityStatement. Be especially wary about any such queries that involve Observation, ResearchSubject, EvidenceVariable, or CodeSystem.

Not all the CodeSystems referenced are recorded as Resources

Not all the CodeSystem links we reference in FHIR Resources' system fields have a CodeSystem Resource.

Observation value-quantity sorts integer values separately from non-integer values

When sorting Observation by value-quantity it sorts integer values separately from non-integer values. So, "1.5, 1, 2.5, 2, 3.5" could be ordered as "1, 2, 1.5, 2.5, 3.5" or "1.5, 2.5, 3.5, 1, 2".

_include and _revinclude are not implemented

_include and _revinclude are listed as implemented in the CapabilityStatement, but are not.

URL links are bad- point to wrong server

In the example, you start with:

http://dbgap-api.ncbi.nlm.nih.gov/fhir/x1/ResearchStudy and get the next page using the link inside the result, which is:

https://dbgap-api-firewalled.ncbi.nlm.nih.gov/fhir/x1?_getpages=8776f07f-4b69-4260-86d1-13708db96d5e&_getpagesoffset=100&_count=100&_pretty=true&_bundletype=searchset

The issue is that link is for a firewalled server, not the public server. The actual address to get the second page is:
https://dbgap-api.ncbi.nlm.nih.gov//fhir/x1?_getpages=8776f07f-4b69-4260-86d1-13708db96d5e&_getpagesoffset=100&_count=100&_pretty=true&_bundletype=searchset

In each page, all of the links (self, next and previous) are displayed as the secure firewall addresses rather than the public ones. Inside each record the fullUrl value is also pointing at the firewalled data.