Reading Platform API Documentation

This section outlines the general formatting conventions and how to read API requests and responses within the documentation.

General Formatting

Our documentation uses specific formatting conventions to enhance clarity and ease of use. Here’s a guide to these conventions:

1. Bold Texts: Bold text is used to highlight actions that need to be taken within a system or application. It also draws attention to buttons or specific functionalities that are crucial to the process. Example: When instructing to Upload Image, the bold text emphasizes the action required.

2. Hyperlinks: Platform API documentation often includes hyperlinks to external sources for additional information or references. These are highlighted texts that, when clicked, will open a new tab in your browser and redirect you to the referenced website. Example: For more details on DICOM standards, visit the DICOM Library (opens new window).

3. Monospaced Font: Sections of text in a monospaced font indicate code samples or file paths. These can be directly copied and pasted into your code or terminal. Example: To get the SOPInstanceUID from a DICOM file, use sop_instance_uid = pydicom.read_file('<PASTE_DICOM_FILE_PATH>').SOPInstanceUID.

4. Angle Brackets: Text within angle brackets <> represents variable information that differs between users or functionalities. These placeholders should be replaced with actual data relevant to your context. Example: In the API call -H 'Authorization: Token <PASTE_YOUR_TOKEN>', replace <PASTE_YOUR_TOKEN> with your actual token. The final input should look like -H ‘Authorization: Token K29j54s8Xm054C357y54p956549U54054`

5. Code Blocks: The documentation includes several code samples presented in blocks. These blocks have a copy option at the top right corner, allowing you to easily copy the code for use in your projects. Example:

{
  title: "Title",
  children: [
    {"Item name"},
    {"Item name"},
    {"Item name"},
    {"Item name"}
  ]
}

Reading Sample API Requests

The format for API requests varies depending on the specific Platform APIs in use. The most effective way to understand how to structure your API calls is by following the examples in the documentation for the service you're using.

The Platform API documentation presents example API requests in two three ways. Initially, the request is shown in its API Format, a template representation. This includes the operation type (GET, POST, PUT, PATCH, DELETE) and the used endpoint (e.g., /studies). Some templates also indicate variable placement, providing a clearer picture of how a call should be structured.

Example:

GET /results/<SOPInstanceUID>

The requests are then presented as Request Formats in various programming languages. This includes the necessary headers and the URL required for successful API interactions. You can choose the programming language from the toggle at the top of the tab and copy the code snippet. Currently, we have only added cURL and Python code snippets, but more will be added in the future.

Ensure that your Base_URL is prefixed to all endpoint URLs. For instance, the /results endpoint is expanded to Base_URL/studies. This pattern is consistent throughout the documentation, and it's expected that you use the complete path when making your own calls to the Platform APIs.

Example:

API Format

Below is an example of an API request in the format encountered in the documentation.

POST /studies

Request Formats

Below are example API requests in various programming languages, presented in the format encountered in the documentation:

cURL

curl -X POST \\
-L 'Base_URL/studies/' \\
-H 'Content-Type: multipart/form-data' \\
-H 'Authorization: Token <PASTE_YOUR_TOKEN>' \\
-H 'Source: <PASTE_YOUR_SOURCE>' \\
-F 'file_1=@"</path/to/your/dicom_file1.dcm>"' \\
-F 'file_2=@"</path/to/your/dicom_file2.dcm>"' \\
-F 'file_3=@"</path/to/your/dicom_file3.dcm>"'

Python

import requests

url = "Base_URL/studies/"

# Prepare the files for upload. Assign each file a unique key.
files = {
    'file_0': ('<dicom_file1.dcm>', open('<path/to/dicom_file1.dcm>', 'rb'), 'application/dicom'),
    'file_1': ('<dicom_file2.dcm>', open('<path/to/dicom_file2.dcm>', 'rb'), 'application/dicom'),
    'file_2': ('<dicom_file3.dcm>', open('<path/to/dicom_file3.dcm>', 'rb'), 'application/dicom')
}

# Headers, including the Authorization token and Source
headers = {
    'Authorization': 'Token <PASTE_YOUR_TOKEN>',
    'Source': '<PASTE_YOUR_SOURCE>',
    'Content-Type: multipart/form-data'
}

# Perform the POST request
response = requests.post(url, headers=headers, files=files)

# Print the response text
print(response.text)

# Close the file handles after the request is done
for file in files.values():
    file[1].close()

Reading Sample API Responses

The response examples will first showcase a Success Response with a '200 OK' status. This illustrates what a correctly executed request would yield. Following this, Other Responses details other possible responses, encompassing various scenarios, reasons and HTTP status codes you might encounter.

Example:

Success Response

This response demonstrates what to expect after a successful API call, corresponding to the sent request. Sometimes, responses are truncated to conserve space, so the actual response may contain more or different information than shown in the sample.

{
    "message": "Success",
    "status": "success",
    "messages": {
        "file0": {
            "message": "DICOM registered successfully.",
            "created": true,
            "license_expired": false,
            "metadata": {
                ...
        }
    },
    "series_instance_uids": [
        "<series_instance_uid>"
    ],
    "detailed_info": [
        {
            "SeriesInstanceUID": "<series_instance_uid>",
            "NumberOfSeriesRelatedInstances": "<number_of_series_related_instances>"
        }
    ]
}

Other Responses

1. 401 Unauthorized

   This response occurs when the Authorization header has either no token or a wrong token.

   {
       "message": "Invalid token header. No credentials provided.",
       "next": "/accounts/login/",
       "authenticated": false
   }

2. 400 Bad Request

   This response is returned when no DICOMs are uploaded.

   {
       "message": "No DICOM files were uploaded!"
   }