VIEW APIs

Authorization

Every HTTP request sent to any of the following API endpoints must include the following header:

CODE

Authorization: {APIkey}

The VIEW will reject any request that does not contain the Authorization header or contains a wrong API Key value. The returned response status in these cases will be HTTP 401 (Unauthorized).

The value of the API key is set in the ServletAuthorizationHeader field of the VIEW’s configuration page.

Access Token API (GET)

The API provides the secure token needed to open one or more studies or the history of a patient in a single monitor.

URL	`/ngv/obscurl`
Method	GET
Request headers	`Authorization`	API Key	Required
Query parameters	See the VIEW APIs \| Access-Token-API-query-parameters section.
Response body	The token to be used as a URL parameter when opening VIEW.

Access Token API (GET) query parameters

Parameter	Type	Multiplicity	Description	Example
`username`	Required	1	It is used for auditing purposes and may not be present in the VIEW database. If there are personalized Hanging Protocols associated with the provided username, VIEW will load them.	`username=janedoe`
`role`	Required	1	It is used to enable specific buttons and functionalities and must be present in the VIEW database. If there are no personalized Hanging Protocols associated with the provided username, VIEW will load those associated with the provided role. If there are no personalized Hanging Protocols associated with the provided role, VIEW will load global Hanging Protocols.	`role=physician`
`studyUID`	Conditionally required	1-n	Unique identifier of the study(ies) to be opened in VIEW (Study Instance UID DICOM attribute). It is required if `accNum` or `patientID` parameters are not provided. If a study does not exist, VIEW will display a “study not found” message.	`studyUID=1.2.826.0.1.3680043.9.6116.181913404117131616172218`
`accNum`	Conditionally required	1	Number that identifies the order for the study(ies) to be opened in VIEW (Accession Number DICOM attribute). It is required if `studyUID` or `patientID` parameters are not provided. If multiple studies share the same Accession Number, they will be opened regardless of the patient to whom they belong.	`accNum=281949768`
`patientID`	Conditionally required	1	Identifier for the patient (Patient ID DICOM Attribute) of whose history is to be displayed in VIEW. The choice of the study to be opened is left to the user. Required if `studyUID` or `accNum` parameters are not provided. If provided in conjunction with `accNum`, VIEW will open all the studies of patient `patientID` having AccessionNumber equal to `accNum`. If no studies are found, then VIEW will open the history of the patient identified by `patientID`	`patientID=PID123`
`historyList`	Optional	1-n	Study Instance UID of the study(ies) to be displayed in the patient history.	`historyList=1.2.826.0.1.3680043.9.6116.181913404117131616172218`
`fullPreloadStudy`	Optional	1-n	Study Instance UID of the study(ies) to be preloaded in memory by VIEW.	`fullPreloadStudy=1.2.826.0.1.3680043.9.6116.181913404117131616172218`
`sticky`	Optional	1	It is used to specify the instance of VIEW to be used. Requests with the same sticky value will be handled by the same server. It requires ad-hoc configuration on the NGINX Reverse Proxy or Ingress and can only be utilized when there are multiple instances of VIEW (e.g., Kubernetes cluster).	`sticky=ah6799c`
`anonymize`	Optional	1	If set to `true`, patient data will be displayed in anonymized form. Default: `false`	`anonymize=false`
`hideSearch`	Optional	1	If set to `true`, the button for study search will be hidden. Default: `true`	`hideSearch=true`
`hideDocuments`	Optional	1	If set to `true`, all documents attached to the opened study(ies) will be hidden. Default: `true`	`hideDocuments=true`
`hideLayers`	Optional	1	Specific for Digital Pathology If set to true, all graphic annotations (Layers) present in the opened case will be hidden. Default: `false`	`hideLayers=true`
`annotationVisibility`	Optional	1	Specific for Digital Pathology If set to `ALL`, graphic annotations (Layers) and snapshots (ROIs) present in the opened case will be visible to all the users. If set to `USER`, graphic annotations (Layers) and snapshots (ROIs) present in the opened case will only be visible to the user that has created them. Default: `ALL`	`annotationVisibility=USER`
`containerIdentifier`	Optional	1	Specific for Digital Pathology The identifier for the digital slide to be displayed (i.e., slide barcode). It must be used in conjunction with the `accNum` parameter, that corresponds to the identifier for the case.	`containerIdentifier=S00000173070000004442`

Access Token API (POST)

The API provides the secure token needed to open files stored on different types of archive systems, such as:

open a specific folder
open a list of files stored in a local filesystem
open files stored on cloud storage systems (GCP buckets or Amazon S3)

URL	`/ngv/v1/obscurl`
Method	POST
Request headers	`Authorization`	API Key	Required
Request body	See the VIEW APIs \| Access-Token-API-(POST)-Request-Body section
Response body	The token to be used as a URL parameter when opening VIEW

Access Token API (POST) Request Body

The request body must be a valid JSON message.

Required parameters:

username
role
one among studies object and folder object
an optional OpeningParameters object

Working with paths

In the following examples, path and file elements that indicate where to read images are locations from the “API consumer” perspective. Since the system runs in a Docker environment with mapped volumes, paths inside a running container may differ from those in the host.

To handle this, configure the system with a mapping table (NgvStorageMapping table on database). This table should include one or more host locations and their corresponding container locations.

If the host path /one/storage is mounted as a volume at /storage-one, and /two/storage is mounted at /storage-two, the NgvStorageMappings should be configured as follows:

Path (host PoV)	Replacement (container PoV)
`/one/storage`	`/storage-one`
`/two/storage`	`/storage-two`

Please note that the system will not read a location that is not included in the mapping table. If a host folder is mounted with the same path inside the container, the table should be configured as follows:

Path (host PoV)	Replacement (container PoV)
/storage	/storage

Request Body examples

Open DICOM files in a folder

Open DICOM files found in the specified folder. Patient and study data will be extracted from the DICOM attributes.

JSON

{
    "username": "john",
    "role": "diagnostic",
    "folder": {
        "path": "/storage/studies/study1"
    }
}

Open DICOM and non-DICOM files

Open a set of DICOM and non-DICOM files. Supported non-DICOM formats include JPEG, PNG, BITMAP, MPEG-4, and PDF. Patient and study data provided in the JSON will have priority over DICOM attributes.

JSON

{
    "username": "john",
    "role": "diagnostic",
    "studies": [
        {
            "patientID": "PID-123",
            "patientName": "DOE^JANE",
            "patientBirthDate": "19821108",
            "patientSex": "F",
            "studyInstanceUID": "1.2.826.123.1",
            "accessionNumber": "AN-123",
            "studyDate": "20231205",
            "studyTime": "123000.000",
            "studyDescription": "File-system images",
            "series": [
                {
                    "seriesInstanceUID": "1.2.826.123.1.1",
                    "seriesDescription": "DICOM",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.1.1",
                            "file": "/storage/images/image-1.dcm",
                            "mimeType": "application/dicom"
                        }
                    ]
                },
                {
                    "seriesInstanceUID": "1.2.826.123.1.2",
                    "seriesDescription": "JPEG",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.2.1",
                            "file": "/storage/images/image-1.jpg",
                            "mimeType": "image/jpeg"
                        }
                    ]
                },
                {
                    "seriesInstanceUID": "1.2.826.123.1.3",
                    "seriesDescription": "PNG",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.3.1",
                            "file": "/storage/images/image-1.png",
                            "mimeType": "image/png"
                        }
                    ]
                },
                {
                    "seriesInstanceUID": "1.2.826.123.1.4",
                    "seriesDescription": "BITMAP",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.4.1",
                            "file": "/storage/images/image-1.bmp",
                            "mimeType": "image/bmp"
                        }
                    ]
                },
                {
                    "seriesInstanceUID": "1.2.826.123.1.5",
                    "seriesDescription": "MPEG4",
                    "modality": "XC",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.5.1",
                            "file": "/storage/images/video-1.mp4",
                            "mimeType": "video/mp4"
                        }
                    ]
                },
                {
                    "seriesInstanceUID": "1.2.826.132.1.6",
                    "seriesDescription": "PDF",
                    "modality": "SR",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.6.1",
                            "file": "/storage/images/report-1.pdf",
                            "mimeType": "application/pdf"
                        }
                    ]
                }
            ]
        }
    ]
}

Open DICOM WSIs

Open a set of digital slides in DICOM file format. The DICOM standard for Whole Slide Imaging (WSI) stores a digital slide by organizing it into multiple instances within a series. Specify one instance of the series to open the associated digital slide. Patient and study data provided in the JSON will have priority over DICOM attributes.

CODE

{
    "username": "john",
    "role": "diagnostic",
    "studies": [
        {
            "patientID": "PID-123",
            "patientName": "DOE^JANE",
            "studyInstanceUID": "1.2.826.123.1",
            "accessionNumber": "C231606-1426",
            "series": [
                {
                    "seriesInstanceUID": "1.2.826.123.1.1",
                    "modality": "SM",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.1.1",
                            "file": "/storage/dicom/C231606-1426-A-1-A.dcm",
                            "mimeType": "application/dicom",
                            "containerIdentifier": "C231606-1426-A-1-1",
                            "specimenIdentifier": "C231606-1426-A",
                            "specimenAlias": "A",
                            "specimenProcedure": "Right lower eyelid",
                            "specimenBodySite": "Bottom of the eye",
                            "blockIdentifier": "C231606-1426-A-1",
                            "blockAlias": "A-1",
                            "blockProcedure":"Margin",
                            "slideIdentifier": "C231606-1426-A-1-A",
                            "slideAlias": "A-1-A",
                            "slideStainCode": "H&E"
                        }
                    ]
                }
            ]
        }
    ]
}

Open non-DICOM WSIs

Open a set of digital slides in non-DICOM file format. Supported file formats are NDPI, MRXS, SVS, and TIFF.

JSON

{
    "username": "john",
    "role": "diagnostic",
    "studies": [
        {
            "patientID": "PID-123",
            "patientName": "DOE^JANE",
            "studyInstanceUID": "1.2.826.123.1",
            "accessionNumber": "C231606-1426",
            "series": [
                {
                    "seriesInstanceUID": "1.2.826.123.1.1",
                    "modality": "SM",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.1.1",
                            "file": "/storage/ndpi/C231606-1426-A-1-A.ndpi",
                            "mimeType": "application/octet-stream",
                            "containerIdentifier": "C231606-1426-A-1-1",
                            "specimenIdentifier": "C231606-1426-A",
                            "specimenAlias": "A",
                            "specimenProcedure": "Right lower eyelid",
                            "specimenBodySite": "Bottom of the eye",
                            "blockIdentifier": "C231606-1426-A-1",
                            "blockAlias": "A-1",
                            "blockProcedure":"Margin",
                            "slideIdentifier": "C231606-1426-A-1-A",
                            "slideAlias": "A-1-A",
                            "slideStainCode": "H&E"
                        }
                    ]
                }
            ]
        }
    ]
}

Open Cloud files (AWS S3)

Open a list of specific files stored on S3.

JSON

{
    "username": "john",
    "role": "diagnostic",
    "studies": [
        {
            "storage": {
                "name": "zeeromed-imaging-test",
                "type": "aws-bucket",
                "region": "eu-central-1",
                "accessKey": "...",
                "secretAccessKey": "..."
            },
            "patientID": "PID-123",
            "patientName": "DOE^JANE",
            "patientBirthDate": "19821108",
            "patientSex": "F",
            "studyInstanceUID": "1.2.826.123.1",
            "accessionNumber": "AN-123",
            "studyDate": "20231205",
            "studyTime": "123000.000",
            "studyDescription": "AWS-bucket images",
            "series": [
                {
                    "seriesInstanceUID": "1.2.826.123.1.1.1",
                    "seriesDescription": "JPEG",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.1.1",
                            "file": "images/image-1.jpg",
                            "mimeType": "image/jpeg"
                        }
                    ]
                },
                {
                    "seriesInstanceUID": "1.2.826.123.1.2",
                    "seriesDescription": "DICOM",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.2.1",
                            "file": "images/images-1.dcm",
                            "mimeType": "application/dicom"
                        }
                    ]
                }
            ]
        }
    ]
}

Open Cloud files (Google Bucket)

Open a list of specific files stored on Google Cloud Bucket.

JSON

{
    "username": "john",
    "role": "diagnostic",
    "studies": [
        {
            "storage": {
                "name": "o3-bucket-test-performance",
                "type": "google-bucket",
                "token": "[base64 encoded service account key]"
            },
            "patientID": "PID-123",
            "patientName": "DOE^JANE",
            "patientBirthDate": "19821108",
            "patientSex": "F",
            "studyInstanceUID": "1.2.826.123.1",
            "accessionNumber": "AN-123",
            "studyDate": "20231205",
            "studyTime": "123000.000",
            "studyDescription": "Google-bucket images",
            "series": [
                {
                    "seriesInstanceUID": "1.2.826.123.1.1",
                    "seriesDescription": "Jpeg",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.1.1",
                            "file": "images/image-1.jpg",
                            "mimeType": "image/jpeg"
                        }
                    ]
                }
            ]
        }
    ]
}

Open Cloud files (WASABI S3)

Open a list of specific files stored on Wasabi.

JSON

{
    "username": "john",
    "role": "diagnostic",
    "studies": [
        {
            "storage": {
                "name": "zeeromed-imaging-test",
                "type": "wasabi-bucket",
                "region": "eu-central-1",
                "accessKey": "...",
                "secretAccessKey": "..."
            },
            "patientID": "PID-123",
            "patientName": "DOE^JANE",
            "patientBirthDate": "19821108",
            "patientSex": "F",
            "studyInstanceUID": "1.2.826.123.1",
            "accessionNumber": "AN-123",
            "studyDate": "20231205",
            "studyTime": "123000.000",
            "studyDescription": "wasabi-bucket images",
            "series": [
                {
                    "seriesInstanceUID": "1.2.826.123.1.1.1",
                    "seriesDescription": "JPEG",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.1.1",
                            "file": "images/image-1.jpg",
                            "mimeType": "image/jpeg"
                        }
                    ]
                },
                {
                    "seriesInstanceUID": "1.2.826.123.1.2",
                    "seriesDescription": "DICOM",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.123.1.2.1",
                            "file": "images/images-1.dcm",
                            "mimeType": "application/dicom"
                        }
                    ]
                }
            ]
        }
    ]
}

Open WADO-RS study

Open a study that can be retrieved through a WADO-RS enabled endpoint.

JSON

{
    "username": "john",
    "role": "diagnostic",
    "studies": [
        {
            "storage": {
                "name": "x-pacs",
                "type": "wado-rs",
                "url": "http://hostname:9002/wado-rs/",
                "httpHeaders": {
                    "Authorization": "x-pacs-api-key"
                }
            },
            "studyInstanceUID": "1.2.826.0.1.8400526.5.8668.5059.20240112"
        }
    ]
}

Open WADO-URI instances

Open a list of DICOM instances that can be retrieved through WADO-URI URLs.

JSON

{
    "username": "john",
    "role": "diagnostic",
    "studies": [
        {
            "storage": {
                "name": "x-pacs",
                "type": "wado-uri",
                "url": "http://hostname:8282/wado",
                "httpHeaders": {
                    "Authorization": "x-pacs-api-key"
                }
            },
            "studyInstanceUID": "1.2.826.0.1.8400526.5.8668.5059.20240112",
            "series": [
                {
                    "seriesInstanceUID": "1.2.826.0.1.8400526.5.8668.5059.20240112.1",
                    "instances": [
                        {
                            "sopInstanceUID": "1.2.826.0.1.8400526.5.8668.5059.20240112.1.1"
                        }
                    ]
                }
            ]
        }
    ]
}

Opening parameters

The thumbnail panel (tray panel in digital pathology) is expanded by default. It is possible to tell the VIEW to show it collapsed when opening an exam, adding the attribute collapsePreviews to the (optional) openingParameters object in the request.

CODE

{
    "username": "john",
    "role": "diagnostic",
    "openingParameters": {
        "collapsePreviews": true
    },
    "studies": [...]
}

Digital Pathology APIs

Post .cube files API

The API allows to save a .cube file into the system and associate it to the related digital slide in order to apply a color profile to the image.

URL	`/webdv/lut`
Method	POST
Request headers	`Authorization`	API Key	Required
Query parameters	`containerIdentifier`	Slide identifier Multiplicity: 1-1	Required
Response code	200 - OK; 400 - Bad request - `containerIdentifier` is mandatory 409 - Conflict - A cube file already exists for this slide

Get ISO API

The API provides a simple way to create an ISO image of the selected study(ies). The computed image will contain a DICOMDIR file containing all the necessary references of the included DICOM files and a standalone viewer (by default Weasis) to visualize them locally.

URL	`/webdv/getIso`
Method	GET
Request headers	`Authorization`	API Key	Required
Query parameters	`studyUID`	Study Instance UID of the study(ies) to be included in the ISO. Multiplicity: 1-n	Required
Response body	ISO image of the selected study(ies).

Multimonitor API

The API provides the secure tokens needed to open one or more studies or the history of a patient in two monitors.

URL	`/ngv/multimonitor-api`
Method	GET
Request headers	`Authorization`	API Key	Required
Query parameters	See the VIEW APIs \| Multimonitor-API-query-parameters section
Response body	JSON `{ "primaryMonitorRelativeUrl":"/ngv?q=62817e1c3fe610e98b73d6ac489fe2b32a38153a3d527764f8b25f850d08008a", "secondaryMonitorRelativeUrl":"/ngv?q=06eebc5cf3459490ded21f2745bd9c554c93f571e593f22a7b1618340fc8b925" }`

Multimonitor API query parameters

Parameter	Type	Multiplicity	Description	Example
`username`	Required	1	It is used for auditing purposes and may not be present in the VIEW database. If there are personalized Hanging Protocols associated with the provided username, VIEW will load them.	`username=janedoe`
`role`	Required	1	It is used to enable specific buttons and functionalities and must be present in the VIEW database. If there are no personalized Hanging Protocols associated with the provided username, VIEW will load those associated with the provided role. If there are no personalized Hanging Protocols associated with the provided role, VIEW will load global Hanging Protocols.	`role=physician`
`patientID`	Required	1	Identifier for the patient (Patient ID DICOM Attribute). If it is not used in conjunction with the `studyInstanceUid` or `accNum` parameter, the patient's history will be displayed and the choice of the study to be opened will be left to the user.	`patientID=PID123`
`numberOfMonitors`	Required	1	Indicates the number of tokens to be returned by the Multimonitor API (i.e. how many monitors will be supported). Possibile values: `1`, `2`.	`numberOfMonitors=2`
`idIssuer`	Conditionally required	1	Identifier of the system, organization, agency, or department) that issued the Patient ID (Isser of Patient ID DICOM Attribute). It is required when `numberOfMonitors=2`.	`idIssuer=NONE`
`studyIntanceUID`	Optional	1-n	Unique identifier of the study(ies) to be opened in VIEW (Study Instance UID DICOM attribute). If a study does not exist, VIEW will display the patient’s history. It can not be used in conjunction with the `accNum` parameter.	`studyIntanceUID=1.2.826.0.1.3680043.9.6116.181913404117131616172218`
`accNum`	Optional	1	Number that identifies the order for the study(ies) to be opened in VIEW (Accession Number DICOM attribute). If multiple studies share the same Accession Number, they will be opened regardless of the patient to whom they belong. It can not be used in conjunction with the `studyInstanceUid` parameter.	`accNum=281949768`
`fullPreloadStudy`	Optional	1-n	Study Instance UID of the study(ies) to be preloaded in memory by VIEW.	`fullPreloadStudy=1.2.826.0.1.3680043.9.6116.181913404117131616172218`
`sticky`	Optional	1	It is used to specify the instance of VIEW to be used. Requests with the same sticky value will be handled by the same server. It requires ad-hoc configuration on the NGINX Reverse Proxy or Ingress and can only be utilized when there are multiple instances of VIEW (e.g., Kubernetes cluster).	`sticky=ah6799c`
`anonymize`	Optional	1	If set to `true`, patient data will be displayed in anonymized form. Default: `false`	`anonymize=false`
`hideSearch`	Optional	1	If set to `true`, the button for study search will be hidden. Default: `true`	`hideSearch=true`
`sourceNodes`	Optional	1	AE Title(s) of DICOM node(s) on which to search for the requested study(ies). Mutliple AE Titles must be separated by “;”.	`sourceNodes=O3-DPACS;TEST`