APIs

The NIMH Data Archive (NDA) provides a variety of web services to support computational scientists, and to facilitate efficient integration between research systems. These direct system-to-system interfaces can be used to both deposit and access NDA data and metadata.  

Below you can find a short description of each available service, and a link that will allow you to access these resources.  These services provide RESTful interfaces, and we are actively updating each to follow the Open API Specification using the Swagger API Framework, including a browser-based User Interface.

In addition to the more modern RESTful services, we provide a legacy SOAP-based service for issuing temporary credentials that can be used with Amazon Web Services S3 API to access content from data files (i.e., raw and analyzed Omics and Neurosignal Recordings data).  More detail on this can be found on the Cloud section of our Tools page.

NDA Web Services have been updated recently. Please visit the Change Documentation section for details.

In addition to the more modern RESTful services, we provide a legacy SOAP-based service for issuing temporary credentials that can be used with Amazon Web Services S3 API to access content from data files (i.e., raw and analyzed Omics and Neurosignal Recordings data).  More detail on this can be found in the Cloud section of our Tools page.

As new services become available they will be documented here.  If you have feedback on an existing service, or ideas for improvements or new services please send them to NDAHelp@mail.nih.gov

 

Examples

Sample code for interacting with the services, including how to obtain AWS authentication tokens and download files, can be found in our GitHub account.

  • AWS-Download is a Python command line script for downloading data files from AWS S3 object storage. Compatible with both Python 2 and Python 3. To download, users can enter a package ID, a data structure file, a .txt file with a list of S3 links, or individual S3 links as arguments.
  • Data Access is a Jupyter Notebook that demonstrates methods to obtain S3 links from an NDAR package and how to programmatically download files from AWS S3 object storage locally using Python. Also includes some sample code for using the APIs.
  • NDA AWS Token Generator contains Bash and Python scripts for obtaining AWS authentication tokens.
  • Brainhack 2017 is a Jupyter Notebook that demonstrates how to access data from a specific GUID, and how to download any associated files from S3 Object storage.
  • Data Staging Services is a Jupyter Notebook that demonstrates how to POST data directly into a miNDAR, and how to upload data to scratch space in S3.

 

Change Documentation

Significant global updates to NDA webservices that could potentially impact existing pipelines are documented below:

March 11, 2019

 

Service Name

Description

Response Formats

Data Dictionary

Provides metadata about all of the measures (data structures) available within the NDA Data Dictionary; including details on the data elements that make up each data structure.

 

This service does not require authentication.

 

Documentation: https://nda.nih.gov/api/datadictionary/v2/docs/swagger-ui.html

Service Endpoint: https://nda.nih.gov/api/datadictionary/v2/

application/json
application/xml

Experiment

Provides metadata on all fMRI, Eye Tracking, and EEG experiments that have been defined by researchers submitting those data for sharing in NDA.

 

This service does not require authentication.

Documentation: https://nda.nih.gov/swagger/#/experiment

Service Endpoint: https://nda.nih.gov/api/experiment

application/json
application/xml

Search

NDA search uses this service to provide search across the entire platform.

Provides the ability to query publicly available content across all of NDA, including Studies, Collections, the Data Dictionary, experiments, and web pages.

 

This service also supports custom Elasticsearch queries against the same search index.

 

This service does not require authentication.

 

Service Endpoint: https://nda.nih.gov/api/search

application/json

 

GUID

Provides a list of all data structures (organized by type) for which the provided GUID has data shared, with an additional operation to retrieve all data for the GUID that the user has access to.

 

Requires HTTP basic authentication.

 

Service Endpoint: https://nda.nih.gov/api/guid

application/json
application/xml

miNDAR

Provides a RESTful interface for depositing data into a miNDAR. Future API services will support validation, packaging, and submission of data from a miNDAR.

 

Additional operations are being added to this service to support listing and retrieval of data from the miNDAR.

 

Requires HTTP basic authentication.

 

Service Endpoint: https://nda.nih.gov/api/mindar

 
Validation

Provides a RESTful interface for validating a data structure before submission to the NDA. The service will return any errors or warnings in the data, and provide a unique UUID to check the status of the validation.

 

Documentation: https://nda.nih.gov/api/validation/docs/swagger-ui.html

Service Endpoint: https://nda.nih.gov/api/validation

application/json
application/xml
Submission Package

A RESTful interface for creating a submission package for multiple data files that have successfully passed validation. Requires the UUID from validation for each file and permission to submit to a collection or alternate endpoint. The service will return a unique UUID for the package that can be used to check the status of the package.

 

Requires HTTP basic authentication.

 

Documentation: https://nda.nih.gov/api/submission-package/docs/swagger-ui.html

Service Endpoint: https://nda.nih.gov/api/submission-package

application/json
application/xml
Submission

Provides a RESTful interface for submitting data into the NDA after all data files have been successfully validated and a submission package created. Requires the UUID from the submission package service. Allows for checking the status of the submission, view all previous submissions, and check the upload status of each individual file in a package.

 

Requires HTTP basic authentication.

 

Documentation: https://nda.nih.gov/api/submission/docs/swagger-ui.html

Service Endpoint: https://nda.nih.gov/api/submission 

application/json
application/xml