NIH | National Cancer Institute | NCI Wiki  

What's New

  • New queries have been added to the API: getManifestForCollection and submitQCVisibility. (July 2019)
  • New APIs were added to NBIA: Host Name and Submission. (December 2019)

Workflow Overview

This document describes the NBIA representational state transfer application programming interface (REST API) implementation for Release 6.0 and up. This API is designed for use by developers of image analysis and data mining tools to directly query the public and private resources of NBIA and retrieve information into their applications. The API complements the existing web interface but eliminates the need for users to visit the NBIA web pages to select and download images and then upload them into their viewing and analysis applications.

The API is a RESTful interface, accessed through web URLs. There is no software that an application developer needs to download to use the API. The application developer can build their own access routines using only the API documentation provided. The interface employs predefined query functions (see REST API Directory) that access NBIA databases.

If you are interested in using the API and have questions, please contact Application Support.

TCIA APIs

Each of the The Cancer Imaging Archive (TCIA) APIs can access either public or restricted data. To access public data using a TCIA API, refer to REST API URL and Format, below. Access to restricted data using a TCIA API requires a token and a different base URL, https://imaging.nci.nih.gov/nbia-api/services/v2/. Find more information about how to request a token at Accessing Private Resources with NBIA REST Services.

TCIA API URL and Format to Access Public Data

The full API for public resources consists of a base URL followed by the API and query parameters, in that order.

For example, in the following URL:

https://imaging.nci.nih.gov/nbia-api/services/v1/getSeries?Collection=RIDER%20Pilot&PatientID=1.3.6.1.4.1.9328.50.1.0001&StudyInstanceUID=1.3.6.1.4.1.9328.50.1.2&format=csv

  • The base URL is https://[installation location]/nbia-api/services/v1/
  • The API endpoint is getSeries
  • The four query parameters are provided as follows:  Collection=RIDER Pilot&PatientID=1.3.6.1.4.1.9328.50.1.0001&StudyInstanceUID=1.3.6.1.4.1.9328.50.1.2&format=csv
  • Data can be obtained in the following formats: CSV, HTML, XML, and JSON.

The order in which the query parameters are provided does not matter.

With the exception of the getImage query, all other queries return a file in one of these data formats: CSV, HTML, XML, and JSON, along with results. The first line of the file contains the names of the columns in the response. Each subsequent line corresponds to one row from the NBIA database. The getImage query returns a ZIP file of the images.

TCIA API URL and Format to Access Public and Private Data

Access to restricted data using a TCIA API requires a token and a different base URL, https://[installation location]/nbia-api/services/v2/. More information about how to request a token is at Accessing Private Resources with NBIA REST Services.

TCIA API Directory

Query NameReturn ValuesOutput FormatQuery Key 1Query Key 2Query Key 3Query Key 4Query Key 5
getBodyPartValuesSet of all body part names filtered by query keysCSV/HTML/XML/JSONCollection (O)
Modality (O)NANA
getCollectionValuesSet of all collection namesCSV/HTML/XML/JSONNANANANANA
getImageSet of images in a zip fileZIPSeriesInstanceUID (R)NANANANA
getManifestForCollection

A manifest file for the given collection and the optional visibility. If visibility is not provided, the manifest file will include all visible series in the given collection.

A manifest filecollection (R)visibility(O)NANANA
getManufacturerValuesSet of all manufacturer names filtered by query keysCSV/HTML/XML/JSONCollection (O)BodyPartExamined (O)Modality (O)NANA
getModalityValuesSet of all modality values (CT, MR, ...) filtered by query keysCSV/HTML/XML/JSONCollection (O)BodyPartExamined (O)
NANA
getPatient


Set of patient objects filtered by query keysCSV/HTML/XML/JSONCollection (O)StudyInstanceUID (O)NANANA
getPatientStudySet of patient/study objects filtered by query keysCSV/HTML/XML/JSONCollection (O)PatientID (O)StudyInstanceUID (O)NANA
getSeriesSet of series objects filtered by query keysCSV/HTML/XML/JSON

Collection (O)

PatientID (O)

StudyInstanceUID (O)Modality (O)NA
getSingleImageA single DICOM Object that is identified by its SeriesInstanceUID and SOPInstanceUID. This API will always be used following the /getSOPInstanceUIDs.Raw DICOM ObjectSeriesInstanceUID (R)SOPInstanceUID (R)NANANA
getSOPInstanceUIDsA list of SOPInstanceUIDs for a given series using the SeriesInstanceUID

CSV/HTML/XML/JSON

SeriesInstanceUID (R)NANANANA
submitQCVisibility

Status code: 400/401/ 412/ 500

Only status code 400 coupled with an "ok" response signals the successful submission. An invalid value for a required key will result in status code 400 with a rejection reason.

401 signals insufficient privileges.

412 signals that some or all of the series need to be submitted into the database first.

500 signals that the server was not able to process your request due to reasons other than the reasons stated above.


project (R)


siteName(R)

seriesId(R)

Note: This key can be repeated for passing multiple seriesIds.

newQcStatus(R)

comment(O)

Return Values for TCIA APIs

This section lists and explains the return values of the TCIA REST APIs.

Collection

An object that represents Collection (project) values.

AttributeDICOM TagDescription
CollectionNAA label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.

Modality

An object that represents Modality values.

AttributeDICOM TagDescription
Modality0008 0060Standard DICOM definition

BodyPartExamined

An object that represents BodyPartExamined values.

AttributeDICOM TagDescription
BodyPartExamined0018 0015Standard DICOM definition

Manufacturer

An object that represents Manufacturer values.

AttributeDICOM TagDescription
Manufacturer0008 0070Standard DICOM definition

Patient

An object that represents one patient.

AttributeDICOM TagDescription
PatientID0010 0020Has been de-identified as part of submission process.
PatientName0010 0010Has been de-identified as part of submission process.
PatientBirthDate0010 0030Has been de-identified as part of submission process.
PatientSex0010 0040Standard DICOM definition
EthnicGroup0010 2160Standard DICOM definition
CollectionNAA label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.

PatientStudy

An object that represents one DICOM imaging study performed on one patient.

AttributeDICOM TagDescription
StudyInstanceUID0020 000DHas been de-identified as part of submission process.
StudyDate0008 0020Has been de-identified as part of submission process. Longitudinal information is preserved.
StudyDescription0008 1030Standard DICOM definition. Has been inspected and cleaned of any PHI
AdmittingDiagnosesDescription0008 1080Standard DICOM definition. Has been inspected and cleaned of any PHI
StudyID0020 0010Has been de-identified as part of submission process.
PatientAge0010 1010Standard DICOM definition
PatientID0010 0020Has been de-identified as part of submission process.
PatientName0010 0010Has been de-identified as part of submission process.
PatientBirthDate0010 0030Has been de-identified (emptied) as part of submission process.
PatientSex0010 0040Standard DICOM definition
EthnicGroup0010 2160Standard DICOM definition
CollectionNAA label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.
SeriesCount
Computed number of series.

Series

An object that represents one imaging series.

AttributeDICOM TagDescription
SeriesInstanceUID0020 000EHas been de-identified as part of submission process.
StudyInstanceUID0020 000DHas been de-identified as part of submission process.
Modality0008 0060Standard DICOM definition
ProtocolName0018 1030Standard DICOM definition. Has been inspected and cleaned of any PHI.
SeriesDate0008 0021Standard DICOM definition
SeriesDescription0008 103EStandard DICOM definition. Has been inspected and cleaned of any PHI.
BodyPartExamined0018 0015Entered on a per collection basis using relevant SNOMED terms.
SeriesNumber0020 0011Standard DICOM definition
AnnotationsFlagNA
CollectionNAA label used to name a set of images collected for a specific trial or other reason. Assigned during the process of curating the data.
PatientID0010 0020Has been de-identified as part of submission process.
Manufacturer0008 0070Standard DICOM definition
ManufacturerModelName0008 1090Standard DICOM definition
SoftwareVersions0018 1020Standard DICOM definition
ImageCountNAComputed number of images in this series.

Image

An object that represents set of images in a ZIP file based on SeriesInstanceUID.

AttributeDICOM TagDescription
NANASet of images in a ZIP file

Access Private Resources with NBIA REST Services

Starting with NBIA Release 6.1, the NBIA REST API supports secure access to private resources in the Client Credentials authorization flow with Spring Security and OAuth2. The Client Credentials authorization flow is also known as "signed fetch" or 2-legged OAuth. The following figure illustrates the typical use case for REST API calls made on the Internet using 2-legged OAuth. For more information regarding the specific workflow, consult the OAuth2 specification  Exit Disclaimer logo .

     +---------+                                  +---------------+
     |         |                                  |               |
     |         |>--(A)- Client Authentication --->| Authorization |
     | Client  |                                  |     Server    |
     |         |<--(B)---- Access Token ---------<|               |
     |         |                                  |               |
     +---------+                                  +---------------+

                     Figure 1: Client Credentials Flow

   The flow illustrated in the preceding Figure includes the following steps:

   (A)  The client authenticates with the authorization server and
        requests an access token from the token endpoint.

   (B)  The authorization server authenticates the client, and if valid, 
issues an access token.

This token can then be used on subsequent requests to authorize access to resources. The NBIA REST Server also supports token expiration and extension token by refresh.

Accessing a Private Resource

Do the following to access a private resource.

  1. Application request credentials, shown below, from resource owner (also known as the user).
    • username
    • password
  2. Application sends a request to the Service using the given credentials as a query string for the body. 
    • grant_type = password
    • username
    • password

    It should look like this:

    grant_type=password&username=my_username&password=my_password 

    These must be passed as well:

    • client_id
    • client_secret

    Which would become:

    grant_type=password&username=my_username&password=my_password&client_id=random_string&client_secret=random_secret
  3. The Service responds with Access Token details and expiration information:
    • access_token
    • expires_in
    • token_type
  4. The application makes a request for private resources using the returned access token. All APIs listed for accessing public resources are supported for secure accessing of private resources with an additional parameter for the access token. 

Example Request for Token

There are many ways to create a REST client using NBIA REST Services. For the purpose of simple illustration, curl is used to show how to request NBIA REST Services for private resources.

# Request for access token
          
$ curl -X -v -d  "username=Tester1&password=Tester1&client_id=nbiaRestAPIClient&client_secret=ItsBetweenUAndMe&grant_type=password" -X POST -k "https://imaging.nci.nih.gov/nbia-api/oauth/token"

The REST client developer must contact Application Support to get a valid client_idclient_secret and, of course, the username and password for accessing the private resource.

A successful token request returns a standard access token in JSON format:

{"access_token":"f7889076-b3e4-4768-9419-3cd973adda76","token_type":"bearer","refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":7199}

Example Request for Accessing a Private Resource

Note down the access token received and pass it with the REST service call.

# Request for modality values
              
$ curl -H "Authorization:Bearer f7889076-b3e4-4768-9419-3cd973adda76" -k "https://imaging.nci.nih.gov/nbia-api/services/v2/getModalityValues"

A successful service request returns the value in a defined format. The example of the returned result for the preceding service call is as follows:

[{"Modality":"CR"},{"Modality":"CT"},{"Modality":"DX"},{"Modality":"HC"},{"Modality":"HISTOPATHOLOGY"},{"Modality":"MR"},{"Modality":"PR"},{"Modality":"PT"},{"Modality":"RTDOSE"},{"Modality":"RTPLAN"},{"Modality":"RTSTRUCT"},{"Modality":"SC"},{"Modality":"SR"},{"Modality":"US"},{"Modality":"XA"}]

Example Request for Refreshing the Token

# Request for refreshing the token  

$curl -X -v -d "refresh_token=671bb72b-f929-4ef5-a4d7-b52341a6007a&client_id=nbiaRestAPIClient&client_secret=ItsBetweenUAndMe&grant_type=refresh_token" -X POST "
-k "https://imaging.nci.nih.gov
        
/nbia-api/oauth/token"

The result:

{"access_token":"bbe4aa2c-7235-41ad-9770-31619d3dbd15","token_type":"bearer","refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":119}

Example Request for Logout

# Request for logout   
      
$curl -H "Authorization:Bearer bbe4aa2c-7235-41ad-9770-31619d3dbd15" -k "https://imaging.nci.nih.gov/nbia-api/logout"

The result:  

 You Have Logged Out successfully.

REST Search Client APIs

As of NBIA 6.4, the application has a REST search API that is used to perform the backend services of the search pages within the portal. The search API uses authorization by default, so that users can access private data. For developers that just need access to public data, each NBIA instance includes a guest user name. Ask the NBIA administrator for this user name; the password for the public user is ignored. Since the purpose of the search API is to provide programmatic access to backend functionality, all service endpoints return JSON except the JNLP endpoint that returns a text file that can be used to invoke Download Manager.

Use of NBIA Search Client APIs requires a token. More information about how to request a token is at Accessing Private Resources with NBIA REST Services.

Advanced Search API

The advanced search API is used in the portal to create queries for the advanced search.  The Advanced Search API is bound to the NBIA configuration DataSourceItem.xml and is like a map of tables and columns.

Developers who want to use the API should focus on:

  • sourceName - The entity to be queried
  • itemName - The field to be queried
<dataSource>
        <sourcePackageName>gov.nih.nci.nbia.internaldomain</sourcePackageName>
        <sourceLabel>Patient</sourceLabel>
        <sourceName>Patient</sourceName>
        <sourceItem>
            <itemLabel>Patient ID</itemLabel>
            <itemName>patientId</itemName>
            <itemType>java.lang.String</itemType>
        </sourceItem>
        <sourceItem>
            <itemLabel>Patient Name</itemLabel>
            <itemName>patientName</itemName>
            <itemType>java.lang.String</itemType>
        </sourceItem>
        <sourceItem>
            <itemLabel>Patient Gender</itemLabel>
            <itemName>patientSex</itemName>
            <itemType>java.lang.String</itemType>
            <itemPrimaryValue>true</itemPrimaryValue>
        </sourceItem>

Developers should also familiarize themselves with the available operators

  • For numbers ">","<",">=","<=","=","!="


  • "starts with","ends with","contains","equals"

The queries consist of two main items:

  • A series of search criteria, which since they can repeat a number at the end provides the order in which to be processed, starting at zero
    • itemName 
    • sourceName
    • value - The value to be used as criteria
    • operator 
  • stateRelation, which is whether to use "and" or "or "in the logic between the search criteria values can be
    • AND
    • OR

Example Advanced Search Query 

curl -H "Authorization:Bearer 946bddb4-d076-4fb1-8dff-81fb64d6f921" -k "http://localhost:8080/nbia-api/services/getDynamicSearch" -d "itemName0=project&sourceName0=TrialDataProvenance&value0=Project&stateRelation=AND&operator0=equals"

Since the API is for programmatic use, JSON is returned, providing the information returned in the initial search screen.

[ {
subjectId" : "Project-2305981223",
  "project" : "Project",
  "id" : 163840,
  "totalNumberOfStudies" : 1,
  "totalNumberOfSeries" : 3,
  "studyIdentifiers" : [ {
    "seriesIdentifiers" : [ 262144, 262148, 262160 ],
    "studyIdentifier" : 196608
  } ]
}, {
  "subjectId" : "Project-3076386612",
  "project" : "Project",
  "id" : 1277952,
  "totalNumberOfStudies" : 1,
  "totalNumberOfSeries" : 1,
  "studyIdentifiers" : [ {
    "seriesIdentifiers" : [ 1376256 ],
    "studyIdentifier" : 1310720
  } ]
}, {
  "subjectId" : "Project-7591268101",
  "project" : "Project",
  "id" : 163841,
  "totalNumberOfStudies" : 1,
  "totalNumberOfSeries" : 1,
  "studyIdentifiers" : [ {
    "seriesIdentifiers" : [ 262145 ],
    "studyIdentifier" : 196609
  } ] } ]

Note that the series identifiers are those that fulfill the search criteria.

Body Part Values and Counts API

The Body Part Values and Counts API will return the modality values plus the body part count for the modality it takes the following parameters optionally

  • Collection
  • Modality

Example Body Part Values and Counts API 

curl -H "Authorization:Bearer c428d42c-9eed-4f5d-8007-416d46be9b52" -k "http://localhost:8080/nbia-api/services/getBodyPartValuesAndCounts?Modality=PT"

The API returns the body parts and their counts

[
{"criteria":"ABDOMEN","count":"13"},
{"criteria":"CHEST","count":"298"},
{"criteria":"Chest","count":"1"},
{"criteria":"HEADNECK","count":"1"},{
"criteria":"Lung","count":"76"},
{"criteria":"THORAX_1_ROUTINE","count":"1"}
]

Collection Description API 

The Collection Description API retrieves Collection Descriptions

The API optionally takes one argument:

  • collectionName - The name of the Collection. If omitted, all collections are returned.

Example Collection Description Query 

C:\>curl -H "Authorization:Bearer 1724fb17-b3a5-488c-9c6f-877f489e0489" -k "http://localhost:8080/nbia-api/services/getCollectionDescriptions?collectionName=IDRI"

The API returns the Search Criteria Descriptions.

[
{"description":"<p>IDRI is a limited access subset of the LIDC collection.  Please view the <a href=\"https://wiki.nci.nih.gov/x/T4PB\" target=\"_blank\">LIDC</a> wiki page for more information about these images.</p>",
"id":1345486850,
"collectionDescTimestamp":null,
"collectionName":"IDRI",
"userName":"kirbyju"}
]

Collection Values and Counts API

The Collection Values and Counts API will return the collections plus the subject count for the collection 

Example Collection Values and Counts API 

curl -H "Authorization:Bearer ac89b752-1c29-4bd6-b999-a12483c9c171" -k "http://localhost:8080/nbia-api/services/getExtendedSimpleSearch" -d "criteriaType0=CollectionCriteria&value0=Project"

 The API returns the collections with their counts

[
{"criteria":"IDRI","count":"614"},
{"criteria":"IDRICONDUIT","count":"66"},
{"criteria":"LIDC","count":"397"},
{"criteria":"RIDER Pilot","count":"130"},
{"criteria":"SportInjury","count":"1"},
{"criteria":"Test","count":"3"},
{"criteria":"Test2","count":"3"}
]

Create Shared List API

The Create Shared List API allows the creation of a shared list.

The API takes four arguments:

  • list - A repeatable parameter for each series you wish to have in the shared list
  • name- Name for the shared list
  • description - Description of the shared ist
  • url - Url of the shared list

Example Create Shared List 

curl -H "Authorization:Bearer 5e3d3b2a-2533-4257-ba76-aa498ab8d269" -k "http://localhost:8080/nbia-api/services/createSharedList" -d "list=88.8.133841977708353813381069288155921822331&list=88.8.326983478845196402838719404831299211067&name=scottslist&description=mydescription&url=testurl"

Drill Down API

The Drill Down API provides the functionality in the portal where the user drills down the studies and series associated with a given user.

The API simply takes a list of series to query, using the parameter "list", that is repeated for each series you want to retrieve.

Example Drill Down Query 

curl -H "Authorization:Bearer 946bddb4-d076-4fb1-8dff-81fb64d6f921" -k "http://localhost:8080/nbia-api/services/getStudyDrillDown" -d "list=1376256&list=262144"

The Drill Down API returns JSON with the information to populate the drill down to study screen. There can be multiple studies.

[ {"studyId" : "88.8.40100432719994870453539459050137164864",
  "date" : 671515200000,
  "description" : "CT CHEST W/O CONTRAST",
  "id" : 1310720,
  "seriesList" : [ {
    "seriesNumber" : "3",
    "seriesUID" : "88.8.326983478845196402838719404831299211067",
    "numberImages" : 9,
    "modality" : "CT",
    "manufacturer" : null,
    "annotationsFlag" : false,
    "annotationsSize" : 0,
    "patientId" : "Project-3076386612",
    "patientPkId" : "1277952",
    "studyId" : "88.8.40100432719994870453539459050137164864",
    "studyPkId" : 1310720,
    "totalSizeForAllImagesInSeries" : 4739336,
    "project" : "Project",
    "description" : "LUNG",
    "dataProvenanceSiteName" : null,
    "manufacturerModelName" : null,
    "softwareVersion" : null,
    "maxFrameCount" : "0",
    "seriesId" : "88.8.326983478845196402838719404831299211067",
    "seriesPkId" : 1376256,
    "exactSize" : 4739336  } ]} ]

Delete Shared List API

The Delete Shared List API allows the deletion of a shared list.

The API takes one argument:

  • name- Name for the shared list

Example Delete Shared List 

curl -H "Authorization:Bearer 5e3d3b2a-2533-4257-ba76-aa498ab8d269" -k "http://localhost:8080/nbia-api/services/deleteSharedList" -d "name=scottslist"

DICOM Metadata by SeriesUID API 

The DICOM metadata by SeriesUID API provides the functionality in the portal where the DICOM data is retrieved from a series.

The API takes one argument:

  • SeriesUID

Example Metadata Query 

C:\curl>curl -H "Authorization:Bearer 25bbea7c-4b8d-4f64-9d95-6ad62313c7d6" -k "http://localhost:8080/nbia-api/services/getDicomTags?SeriesUID=9999.266036705757333804188405684898037929022

The API will send back triples of all DICOM element, name, data in the file.

[
{"element":"(0002,0001)","name":"File Meta Information Version","data":"00\\01"},
{"element":"(0002,0002)","name":"Media Storage SOP Class UID","data":"1.2.840.10008.5.1.4.1.1.2"}
...................................

Drill Down API Using SeriesUIDs

The Drill Down API provides the functionality in the portal where the user drills down the studies and series associated with a given user.

The API simply takes a list of SeriesUIDs to query, using the parameter "list", that is repeated for each SeriesUIDS you want to retrieve.

Example Drill Down Using SeriesUIDs Query 

curl -H "Authorization:Bearer 5e3e2193-55dc-43b5-b11a-70fee2ccf50f" -k "http://localhost:8080/nbia-api/services/getStudyDrillDownWithSeriesIds" -d "list=88.8.327219764444138790630242591550292040652&list=88.8.48940758713094405889891485363115655700"

The Drill Down API returns JSON with the information to populate the drill down to study screen. There can be multiple studies.

[ {"studyId" : "88.8.40100432719994870453539459050137164864",
  "date" : 671515200000,
  "description" : "CT CHEST W/O CONTRAST",
  "id" : 1310720,
  "seriesList" : [ {
    "seriesNumber" : "3",
    "seriesUID" : "88.8.326983478845196402838719404831299211067",
    "numberImages" : 9,
    "modality" : "CT",
    "manufacturer" : null,
    "annotationsFlag" : false,
    "annotationsSize" : 0,
    "patientId" : "Project-3076386612",
    "patientPkId" : "1277952",
    "studyId" : "88.8.40100432719994870453539459050137164864",
    "studyPkId" : 1310720,
    "totalSizeForAllImagesInSeries" : 4739336,
    "project" : "Project",
    "description" : "LUNG",
    "dataProvenanceSiteName" : null,
    "manufacturerModelName" : null,
    "softwareVersion" : null,
    "maxFrameCount" : "0",
    "seriesId" : "88.8.326983478845196402838719404831299211067",
    "seriesPkId" : 1376256,
    "exactSize" : 4739336  } ]} ]

Drill Down to Images API

The Drill Down to Images API allows the developer to drill down to the images in a series and have the information available to create a WADO call that can retrieve the images themselves. This API  is used to create the Thumbnails screen in the portal.

The API simply takes a list of series to query, using the parameter "list", that is repeated for each series you wish to retrieve the images for.

Example Drill Down to Images Query 

curl -H "Authorization:Bearer 946bddb4-d076-4fb1-8dff-81fb64d6f921" -k "http://localhost:8080/nbia-api/services/getImageDrillDown" -d "list=1376256&list=262144"

 The API returns the information needed to populate the Thumbnails screen.

[ {  "imagePkId" : 1409028,
  "contentDate" : null,
  "contentTime" : null,
  "seriesPkId" : 1376256,
  "instanceNumber" : 73,
  "sopInstanceUid" : "88.8.73811183841243046367164226375699603900",
  "seriesInstanceUid" : "88.8.326983478845196402838719404831299211067",
  "studyInstanceUid" : "88.8.40100432719994870453539459050137164864",
  "size" : 526592,
  "fileURI" : "C:\\projects\\NBIA\\nbia-install_6.3\\CTP-server\\CTP\\storage\\0000000000\\000\\000\\006.dcm",
  "project" : null,
  "siteName" : null,
  "frameNum" : 0
}, {
  "imagePkId" : 1409024,
  "contentDate" : null,
  "contentTime" : null,
  "seriesPkId" : 1376256,
  "instanceNumber" : 85,
8<------------------------------------------------------------------------------->8

The information needed to create a WADO call is the following snippet from this code:

  "sopInstanceUid" : "88.8.73811183841243046367164226375699603900",
  "seriesInstanceUid" : "88.8.326983478845196402838719404831299211067",
  "studyInstanceUid" : "88.8.40100432719994870453539459050137164864",

Extended Simple Search API

The extended simple search API adds two new fields to be returned 

Example Extended Simple Search Query 

curl -H "Authorization:Bearer ac89b752-1c29-4bd6-b999-a12483c9c171" -k "http://localhost:8080/nbia-api/services/getExtendedSimpleSearch" -d "criteriaType0=CollectionCriteria&value0=Project"

 The API returns the simple search with additional information

[ {
subjectId" : "Project-2305981223",
  "project" : "Project",
  "id" : 163840,
  "totalNumberOfStudies" : 1,
  "totalNumberOfSeries" : 3,
  "studyIdentifiers" : [ {
    "seriesIdentifiers" : [ 262144, 262148, 262160 ],
    "studyIdentifier" : 196608
  } ]
  "diskSpace": 54321012,
  "imageCount 43212,
} ]

Host Name API

The Host Name returns a short host name used by the client to display which machine in a load-balanced environment is running.

Example Series Metadata API

C:\curl>curl -H "Authorization:Bearer 6ea24d8c-00a3-4a9f-b4e9-faaaf949c598" -k "http://localhost:8080/nbia-api/services/getHostName" -d 

The API returns a short host name.

 tcia-public-rh-1

JNLP API

The JNLP API allows the creation of a JNLP file that can be used to execute Download Manager, it is the only API that returns a text file.

The API takes three arguments:

  • list - A repeatable parameter of series UIDs for each series you wish to download
  • password - The user password necessary for Download Manager to authenticate to the download servlet
  • includeAnnotation - If "true" is used, the annotations are returned.

Example JNLP Query 

curl -H "Authorization:Bearer fe33c0f9-cf1e-48b9-ac01-ea9a749cb010" -k "http://localhost:8080/nbia-api/services/getJNLPText" -d "list=1.3.6.1.4.1.9328.50.17.37921787632413562465489028998404818008&list=1.3.6.1.4.1.9328.50.17.42844868073432865072113108706857915664&list=1.3.6.1.4.1.9328.50.17.54740991639976922135022058762719650327&list=1.3.6.1.4.1.9328.50.17.63007857457742009673233119066667590523&password=mysecret&includeAnnotation=false"

The API returns text that can be used as a JNLP file for Download Manager.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!-- JNLP File  --><jnlp codebase="https://imaging.nci.nih.gov/ncia/" spec="1.0+">
 
  <information>
    <title>NBIA Download Manager</title>
    <vendor>NCICB</vendor>
    <description>NBIA Download Manager</description>
    <homepage href="https://imaging.nci.nih.gov/ncia/welcome.jsp"/>
    <description kind="short">NBIA Download Manager</description>
  </information>
 
  <application-desc main-class="gov.nih.nci.nbia.Application">
    <argument>/tmp/jnlp-data1461322903660.txt</argument>
  </application-desc>
 
  <security>
    <all-permissions/>
  </security>
  <update check="always" policy="always"/>
<------------------------------------------------------------------------------->8

The file that has the details for Download Manager is:

<argument>/tmp/jnlp-data1461322903660.txt</argument>

Manufacturer Values and Counts API

The Manufacturer Values and Counts API will return the modality values plus the manufacturer count for the modality it takes the following parameters optionally

  • Collection
  • Modality
  • Body Part Examined

Example Manufacturer Values and Counts API 

curl -H "Authorization:Bearer c428d42c-9eed-4f5d-8007-416d46be9b52" -k "http://localhost:8080/nbia-api/services/getManufacturerValuesAndCounts?Modality=PT"

The API returns the manufacturer and their counts.

[
{"criteria":"DeJarnette Research Systems","count":"2"},
{"criteria":"FUJI PHOTO FILM Co., ltd.","count":"4"}
]

Manufacturer Tree API

The Manufacturer Tree API will return the manufacturer and software in a structure that allows the build of a tree.

Example Manufacturer Values and Counts API 

curl -H "Authorization:Bearer  3ecccd7d-9d72-4424-bd81-757d79cd44aa" -k "http://localhost:8080/nbia-api/services/getManufacturerTree"

The API returns the manufacturer and their counts.

{"data":{"criteria":"root","value":"All Manufactures"},
"children":[{"data":{"criteria":"Manufacturer","value":"CMS, Inc."},
"children":[{"data":{"criteria":"Model","value":"XiO"},
"children":[{"data":{"criteria":"Software Ver.","value":"4.51.00"},
"children":[]},{"data":{"criteria":"Software Ver.","value":"4.51.02"},"children":[]}]}]},
{"data":{"criteria":"Manufacturer","value":"CPS"},
"children":[{"data":{"criteria":"Model","value":"1024"}
8<------------------------------------------------------------------------------->8

Manifest API

The Manifest API allows the creation of a manifest file that can be used to execute the Downloader App.

The API takes two arguments:

  • list - A repeatable parameter of series UIDs for each series you want to download
  • includeAnnotation - If "true" is used, the annotations are returned.

Example Manifest Query 

curl -H "Authorization:Bearer d98c390f-b53d-4456-beb3-110e63663762" -k "http://localhost:8080/nbia-api/services/getManifestTextV2" -d "list=1.3.6.1.4.1.9328.50.3.336&includeAnnotation=false"

The API returns text that can be used as a manifest file for the Downloader App.

downloadServerUrl=https://imaging-devcm.nci.nih.gov/nbia-download/servlet/DownloadServlet
includeAnnotation=false
noOfrRetry=4
databasketId=manifest-1523866570303.tcia
manifestVersion=3.0
ListOfSeriesToDownload=
1.3.6.1.4.1.9328.50.3.336

Manifest API from Shared List

The Manifest API from Shared List allows the creation of a manifest file that can be used to execute the Downloader App.

The API takes two arguments:

  • sharedList - The name of the shared list
  • includeAnnotation - If "true" is used, the annotations are returned.

Example Manifest from Shared List Query 

curl -H "Authorization:Bearer a99171a1-b289-4700-9e4e-1bd73ce1bbb5" -k "http://localhost:8080/nbia-api/services/getManifestTextFromSharedList" -d "sharedList=scottslist&includeAnnotation=false"

The API returns text that can be used as a manifest file for the Downloader App.

downloadServerUrl=https://imaging-devcm.nci.nih.gov/nbia-download/servlet/DownloadServlet
includeAnnotation=false
noOfrRetry=4
databasketId=manifest-1523866570303.tcia
manifestVersion=3.0
ListOfSeriesToDownload=
1.3.6.1.4.1.9328.50.3.336

Manifest API from JNLP Data

The Manifest API from JNLP data allows the creation of a manifest file that can be used to execute the Downloader App.

The API takes two arguments:

  • jnlpArgument- The value of the argument in the JNLP file
  • includeAnnotation - If "true" is used, the annotations are returned.

Example Manifest from JNLP Data Query 

curl -H "Authorization:Bearer 3b2bf812-a97e-454e-af94-623b868a2955" -k "http://localhost:8080/nbia-api/services/getManifestFromJNLPFileData" -d "jnlpArgument=C:\Apps\nbia\apache-tomcat-7.0.68\temp\jnlp-data1521628213301.txt&includeAnnotation=false"

The API returns text that can be used as a manifest file for the Downloader App.

downloadServerUrl=https://imaging-devcm.nci.nih.gov/nbia-download/servlet/DownloadServlet
includeAnnotation=false
noOfrRetry=4
databasketId=manifest-1523866570303.tcia
manifestVersion=3.0
ListOfSeriesToDownload=
1.3.6.1.4.1.9328.50.3.336

Modality Values and Counts API

The Modality Values and Counts API will return the modality values plus the subject count for the modality it takes the following parameters optionally

  • Collection
  • BodyPartExamined

Example Modality Values and Counts API 

curl -H "Authorization:Bearer c428d42c-9eed-4f5d-8007-416d46be9b52" -k "http://localhost:8080/nbia-api/services/getModalityValuesAndCounts?Collection=LIDC"


The API returns the modalities and their counts

[
{"criteria":"CT","count":"397"}
]

Series Metadata API

The Series Metadata API allows returns the metadata needed by the Client for a set of series as CSV

The API takes one argument:

  • list- Comma separated list of series to return

Example Series Metadata API

curl -H "Authorization:Bearer 1be042c4-2506-4ecc-9c5e-9556506896aa" -k "http://localhost:8080/nbia-api/services/getSeriesMetadata2" -d "list=9999.293545899757968087866143572947417050996,9999.172212451609088872857235914630319746611"

The API returns ok if successful, and the error if one occurs.

"Subject ID","Study UID","Study Description","Study Date","Series ID","Series Description","Number of images","File Size (Bytes)","Collection Name","Modality","Manufacturer"
"LIDC-IDRI-1009708434","9999.80530326108514806420601956698897575003","CT CHEST O CONTR","1999-12-21 00:00:00.0","9999.172212451609088872857235914630319746611","","268","141000690","LIDC-IDRI","CT","GE MEDICAL SYSTEMS"
"LIDC-IDRI-1001617569","9999.217840977308171348409694654150334249839","","1999-12-21 00:00:00.0","9999.293545899757968087866143572947417050996","","46","24199232","LIDC-IDRI","CT","SIEMENS"

Shared List Data API

The Share List Data API retrieves the data associated with a Shared List

The API takes one argument:

  • nameValue - The name of the Shared List

Example Shared List Data Query 

curl -H "Authorization:Bearer 6143882e-fd9d-4269-9d67-f4293afe417f" -k "http://localhost:8080/nbia-api/services/getSharedList" -d "nameValue=scottslist"

The API will send back the Shared List data.

{"name":"scottslist",
"comment":"",
"hyperlink":"//",
"date":1502078400000,
"id":7798784,
"userName":"sgustaf",
"seriesInstanceUIDs":["88.8.327219764444138790630242591550292040652","88.8.48940758713094405889891485363115655700"],
"seriesInstanceUidsList":null,
"usageCount":null,
"dateString":"2017-08-07"}

Simple Search API

The Simple Search API is used to run queries for the Simple search in NBIA, the Simple Search API uses a variety of criteria as seen in the Simple Search Screen. The available criteria types include and their components are:

  • CollectionCriteria
    • value
  • ImageModalityCriteria
    • value
  • AnatomicalSiteCriteria
    • value
  • ManufacturerCriteria
    • value
  • DateRangeCriteria
    • fromDate - Formatted "dd/mm/yyyy"
    • toDate - Formatted "dd/mm/yyyy"
  • PatientCriteria
    • value
  • MinNumberOfStudiesCriteria
    • value

Since the Simple Search API can take an unlimited number of criteria each of the criteria items is appended with a number signifying its order in the query, starting with 0.

Example Simple Search Query 

curl -H "Authorization:Bearer 946bddb4-d076-4fb1-8dff-81fb64d6f921" -k "http://localhost:8080/nbia-api/services/getSimpleSearch" -d "criteriaType0=AnatomicalSiteCriteria&value0=LUNG&criteriaType1=CollectionCriteria&value1=Project"

The Simple Search API returns the same JSON as the Advanced Search API.

Submission API

The Submission API allows images to be imported into the NBIA database and text index without being submitted through CTP.  Note the API does not create thumbnails as it is assumed that they have already been created.

The API takes up to seven arguments:

  • project- The collection.
  • siteName- The site name.
  • siteID- The site ID.
  • batch- The batch if necessary.
  • thirdPartyAnalysis- yes if a third party analysis
  • descriptionURI- The uri of the description of third party analysis
  • uri- The location of the image files

Example Submission API

curl -H "Authorization:Bearer 0d9ad4b6-153b-4777-a506-358e3411b3ae" -k "http://localhost:8080/nbia-api/services/submitDICOM" -d "project=CBIS-DDSM&siteName=CBIS-DDSM&siteID=99&batch=8
&uri=C:/a/000002.dcm"

The API returns "ok" if successful and the error if one occurs.

Text Search API

The text search API is used to run queries for Text Search in the portal.  The text search takes an argument, textValue.

Example Text Search Query 

curl -H "Authorization:Bearer 946bddb4-d076-4fb1-8dff-81fb64d6f921" -k "http://localhost:8080/nbia-api/services/getTextSearch" -d "textValue=lung"

 Note that the returned JSON now includes the "hit" that was found by the Solr search engine.

[{
"subjectId":"Project-3076386612",
 "project":"Project",
 "id":1277952,
 "totalNumberOfStudies":1,
 "totalNumberOfSeries":1,
 "hit":"<em>seriesDesc</em>: <strong>LUNG</strong>",
 "studyIdentifiers":[{
 "seriesIdentifiers":[1376256],
 "studyIdentifier":1310720
 }]
}]

User Administration APIs

This section describes the group of APIs used internally by NBIA's User Authorization Tool (UAT). The user administration information is considered a private resource and is protected by NBIA's OAauth 2 API server, which allows access only by authorized users. For details on accessing private resources using the NBIA REST service, see Accessing Private Resources with NBIA REST Services.

Assuming the user has been authenticated and has received the OAuth token for the HTTP headers of the API calls, that user can refer to the following table for the parameters for each query endpoint in the UAT APIs. The server returns either the status of the operation or the data requested in the format specified in the query parameter. However, the query parameter for format is optional. If it is not provided, the response returns data in JSON format.

Access to the user administration APIs equires a token and a different base URL, https://imaging.nci.nih.gov/nbia-api/services/v3.

Resource

QueryEndpoint

Query Parameters

All query parameters are optional unless stated otherwise.

Return

Description

v3/

assignDataSetToPG

projAndSite(R)

PGName(R)

The status of operation

Assign a combination of Project and Site to a Protection Group

v3/

assignGroupToPGWithRoles

groupName(R)

PGName(R)

roleNames(R)

The status of operation

Assign a group to a protection group with a role

v3/

assignPEsToPG

PENames(R)

PGName(R)

The status of operation

Assign a list of combination of Project and Site to a Protection Group

v3/

assignUserToPGWithRoles

loginName(R)

PGName(R)

roleNames(R)

The status of operation

Assign an user to a protection group with a role

v3/

createProtecionGroup

PGName(R)

description

The status of operation

Create a new Protection Group

v3/

createUser

loginName(R)

email(R)

active(R)

The status of operation

Create a new user

v3/

deassignDataSetFromPG

projAndSite(R)

PGName(R)

The status of operation

De-assign a combination of Project and Site from a Protection Group

v3/

deassignPEsFromPG

PENames(R)

PGName(R)

The status of operation

De-assign a list of combination of Project and Site from a Protection Group

v3/

deassignUserFromPGWithRoles

loginName(R)

PGName(R)

roleNames(R)

The status of operation

De-assign an user from a protection group with a role

v3/

deleteGroup

GroupName(R)

The status of operation

Delete a Group

v3/

deleteProtecionGroup

PGName(R)

The status of operation

Delete a Protection Group

v3/

getAllGroupsWithPGs

format

CSV/HTML/XML/JSON

Get all groups with associated protection groups

v3/

getAllPGsWithPEs

format

CSV/HTML/XML/JSON

Get all protection groups with associated protection elements

v3/

getAllPGsWithRolesForUser

loginName(R)

format

CSV/HTML/XML/JSON

Get protection group and roles associated with given user

v3/

getAllUsersWithRolesForPG

format

CSV/HTML/XML/JSON

Get all users with associated protection group and roles

v3/

getAvailablePEsForPG

PGName (R)

format

CSV/HTML/XML/JSON

Get the list of protection element names associated with a given protection group

v3/

getAvailablePGsForGroup

groupName (R)

format

CSV/HTML/XML/JSON

Get the list of protection element associated with the given group name

v3/

getAvailablePGsForUser

loginName (R)

format

CSV/HTML/XML/JSON

Get the list of protection group associated with the given user

v3/

getGroupList

format

CSV/HTML/XML/JSON

Get all group names

v3/

getIncludedPEsForPG

PGName (R)

format

CSV/HTML/XML/JSON

Get the list of protection element in the given protection group

v3/

getProjSiteList

format

CSV/HTML/XML/JSON

Get the list of <Project Name>//<Site Name>

v3/

getProtectionEleNameList

format

CSV/HTML/XML/JSON

Get all protection elements

v3/

getProtectionGrpList

format

CSV/HTML/XML/JSON

Get all protection group objects

v3/

getProtectionGrpNameList

format

CSV/HTML/XML/JSON

Get all protection group names

v3/

getRoleList

format

CSV/HTML/XML/JSON

Get all role names

v3/

getUserList

format

CSV/HTML/XML/JSON

Get all user objects

v3/

getUserNameList

format

CSV/HTML/XML/JSON

Get all user login names

v3/

modifyProtecionGroup

PGName(R)

Description(R)

The status of operation

Modify the description of a given Protection Group

v3/

modifyRolesOfGroupForPG

groupName(R)

PGName(R)

roleNames(R)

The status of operation

Modify a group’s roles with a given Protection Group

v3/

modifyRolesOfUserForPG

loginName(R)

PGName(R)

roleNames(R)

The status of operation

Modify a user’s roles win a given Protection Group

v3/

modifyUser

loginName(R)

email(R)

active(R)

The status of operation

Modify the given user’s email and/or active status

v3/

removeGroupFromPG

groupName(R)

PGName(R)

The status of operation

Remove a group from a protection Group

v3/

removeUserFromPG

loginName(R)

PGName(R)

The status of operation

Remove a user from a Protection Group                                 

  • No labels