Usage Guide

This documentation describes the steps for developers to authenticate and interact with the API to manage their API keys and work with DICOM files.

Prerequisites

Before interacting with the API, developers must have an account on our platform and obtain an access token. This token will be used for authentication in subsequent requests.

Endpoints that do not require authentication

1. Get Allowed DICOM Fields

This endpoint retrieves a list of allowed DICOM fields that can be used in queries or processing. You can filter the results using optional query parameters.

Endpoint

• URL: /api/dicom-format/allowed-fields/

• Method: GET

• Description: Returns a JSON object containing the list of allowed DICOM fields, with optional filtering based on query parameters.

Request

• Headers: - Authorization: ApiKey your_api_key_here - Content-Type: application/json

• Query Parameters (Optional):

  • fields__contains – Returns fields containing the specified substring.

  • fields__startswith – Returns fields that start with the specified substring.

  • fields__endswith – Returns fields that end with the specified substring.

  • fields__regex – Returns fields matching a specified regex pattern.

Example Request:

GET /api/dicom-format/allowed-fields/?fields__contains=Patient HTTP/1.1
Host: localhost:8080
Authorization: ApiKey amRqSgZZ....

Response

If successful, the API returns a JSON object containing the list of allowed DICOM fields along with the DICOM standard version.

Example Response:

{
    "allowedFields": [
        "PatientName",
        "PatientID",
        "PatientBirthDate",
        "PatientSex",
        "PatientAge",
        "PatientWeight",
        "PatientAddress",
        "PatientTelephoneNumbers",
        "PatientState",
        "PatientInsurancePlanCodeSequence"
    ],
    "dicomVersion": "3.0.1"
}

Explanation of Response Fields

• allowedFields: A list of DICOM fields that are allowed for use.

• dicomVersion: The version of the DICOM standard used by the system.

1. Get Required DICOM Field Types

This endpoint provides a list of required DICOM fields along with their expected data types.

Endpoint

• URL: /api/dicom-format/required-field-type/

• Method: GET - Description: Returns a JSON object containing the required DICOM field types and the DICOM standard version used.

Request

• Headers:

  • Authorization: ApiKey your_api_key_here

  • Content-Type: application/json

Example Request:

GET /api/dicom-format/required-field-type/ HTTP/1.1
Host: localhost:8080
Authorization: ApiKey amRqSgZZ....

Response

If successful, the API returns a JSON object containing the required DICOM field types and the DICOM version.

Example Response:

{
    "requiredFieldTypes": {
        "CommandGroupLength": "<class 'int'>",
        "CommandLengthToEnd": "<class 'int'>",
        "AffectedSOPClassUID": "<class 'pydicom.uid.UID'>",
        "RequestedSOPClassUID": "<class 'pydicom.uid.UID'>",
        "CommandRecognitionCode": "<class 'str'>",
        "CommandField": "<class 'int'>",
        "MessageID": "<class 'int'>",
        "MessageIDBeingRespondedTo": "<class 'int'>",
        "Initiator": "<class 'str'>",
        "Receiver": "<class 'str'>",
        "FindLocation": "<class 'str'>",
        "MoveDestination": "<class 'str'>",
        "Priority": "<class 'int'>",
        "CommandDataSetType": "<class 'int'>",
        "NumberOfMatches": "<class 'int'>",
        "ResponseSequenceNumber": "<class 'int'>",
        "Status": "<class 'int'>",
        "OffendingElement": "<class 'tuple'>",
        "ErrorComment": "<class 'str'>",
        "ErrorID": "<class 'int'>",
        "AffectedSOPInstanceUID": "<class 'pydicom.uid.UID'>",
        "RequestedSOPInstanceUID": "<class 'pydicom.uid.UID'>",
        "EventTypeID": "<class 'int'>",
        "AttributeIdentifierList": "<class 'tuple'>",
        "ActionTypeID": "<class 'int'>",
        "NumberOfRemainingSuboperations": "<class 'int'>",
        "NumberOfCompletedSuboperations": "<class 'int'>",

        "....": "...",

        "FloatPixelData": "<class 'bytes'>",
        "DoubleFloatPixelData": "<class 'bytes'>",
        "PixelData": "<class 'str'>",
        "CoefficientsSDVN": "<class 'bytes'>",
        "CoefficientsSDHN": "<class 'bytes'>",
        "CoefficientsSDDN": "<class 'bytes'>",
        "DigitalSignaturesSequence": "<class 'str'>",
        "DataSetTrailingPadding": "<class 'bytes'>",
        "Item": "<class 'str'>",
        "ItemDelimitationItem": "<class 'str'>",
        "SequenceDelimitationItem": "<class 'str'>"
    },
    "dicomVersion": "3.0.1"
}

Explanation of Response Fields

• requiredFieldTypes: A dictionary where keys represent DICOM field names and values represent their expected Python data types.

• dicomVersion: The version of the DICOM standard used by the system.

Authentication

1. Obtain an Access Token

To interact with the API, developers must first authenticate by obtaining an access token. This token will be used in the Authorization header to make authenticated requests.

Endpoint:

• URL: /api/token/

• Method: POST

• Description: This endpoint accepts user credentials and returns an access token and a refresh token.

Request

You need to send a POST request to the api/token/ endpoint with the following payload:

{
  "email": "user5@example.com",
  "password": "securepassword123"
}

Response

If authentication is successful, you’ll receive a response containing the access and refresh tokens:

{
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV......"
}

• access: Use this token in the Authorization header as Bearer <access_token> for authenticated requests.

• refresh: Use this token to refresh the access token when it expires.

Developer Profile

Once you have the access token, you need to create a developer profile before you can obtain an API key.

2. Create a Developer Profile

To register your profile as a developer, send a POST request to the api/developer/profiles/ endpoint with the following details.

Endpoint:

• URL: /api/developer/profiles/

• Method: POST

• Description: This endpoint creates a new developer profile.

Request

Include the Authorization header with your Bearer access token and the profile information in the request body:

{
  "purpose": "testing",
  "organization": "My Organization"
}

Response

If the profile creation is successful, you will receive a 201 Created status along with the details of your new profile:

{
  "purpose": "testing",
  "organization": "My Organization"
}

• Status 201 Created: Indicates that the profile has been successfully created.

API Key Management

After creating your developer profile, you can obtain and manage your API keys.

3. List and Create API Keys

Once your profile is set up, you can create and list your API keys.

Endpoint:

• URL: /api-keys/

• Method: GET, POST

• Description: - GET: Retrieves the list of API keys associated with your developer profile. - POST: Creates a new API key for your developer profile.

Request

To list the API keys, send a GET request with the Authorization header:

GET /api-keys/ HTTP/1.1
Authorization: Bearer <access_token>

To create a new API key, send a POST request with the following JSON payload:

POST /api-keys/ HTTP/1.1
Authorization: Bearer <access_token>

{
  "name": "New API Key"
}

Response

• GET `/api-keys/`: - Status 200 OK: A list of API keys.

• POST `/api-keys/`: - Status 201 Created: The newly created API key.

Example Response for POST:

{
  "id": 1,
  "name": "New API Key",
  "key": "API_KEY_12345"
}

• key: This is the actual API key you will use to authenticate API requests.

4. Delete API Key

You can delete an existing API key by specifying its ID.

Endpoint:

• URL: /api-keys/delete/<str:pk>/

• Method: DELETE

• Description: Deletes the specified API key.

Request

To delete an API key, send a DELETE request to the URL /api-keys/delete/<pk>/ with the Authorization header:

DELETE /api-keys/delete/1/ HTTP/1.1
Authorization: Bearer <access_token>

Response

If the deletion is successful, the API will return a 204 No Content status:

{
  "detail": "Key deleted successfully."
}

Example API Key Flow

Here’s a step-by-step example to help you understand the process:

1. Obtain an Access Token

Send a POST request to the /api/token/ endpoint with your email and password:

{
  "email": "user5@example.com",
  "password": "securepassword123"
}

Response:

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

2. Create Developer Profile

Use the access token to create your developer profile by sending a POST request to /api/developer/profiles/:

{
  "purpose": "testing",
  "organization": "My Organization"
}

Response:

{
  "purpose": "testing",
  "organization": "My Organization"
}

3. Create an API Key

With the developer profile created, you can now request your API key. Send a POST request to /api-keys/:

{
  "name": "New API Key"
}

Response:

{
  "id": 1,
  "name": "New API Key",
  "key": "API_KEY_12345"
}

Endpoints for DICOM support

1. DICOM File Upload and Image Retrieval

To upload a DICOM file for processing and retrieve image data, you need to send a POST request to the /api/dicom/read/file/ endpoint. The request should include the following:

Endpoint:

• URL: /api/dicom/read/file/

• Method: POST

• Description: This endpoint allows developers to upload a DICOM file, process it, and receive a response with DICOM metadata along with image data in the desired format.

Request

• Headers: - Authorization: ApiKey amRqSg….

• Body: The request body should contain the following parameters: - file: The DICOM file to be uploaded. - fields (optional): A comma-separated list of specific DICOM fields you wish to retrieve. If this is not provided, all fields will be included. - return_format (optional): The desired image format for the response. Valid values are gif, png, and jpeg.

Example Request:

POST /api/dicom/read/file/ HTTP/1.1
Host: localhost:8080
Authorization: ApiKey amRqSgZZ.CLevHmvt7WJucw2gKA5sGhEUs2Fh6Svq
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="dicom-file.dcm"
Content-Type: application/dicom

<binary DICOM file content>

--boundary
Content-Disposition: form-data; name="fields"

PatientName,StudyDate,Modality

--boundary
Content-Disposition: form-data; name="return_format"

png
--boundary--

Parameters: - file (required): The DICOM file to upload. Must be one of the following formats: .dcm, .DCM, .zip. - fields (optional): A comma-separated list of specific DICOM fields to retrieve. If not provided, all available fields will be returned. - return_format (optional): The image format you prefer for the response. Valid options are: gif, png, jpeg

Response

Upon successful processing of the file, you will receive a response containing DICOM metadata and the image in the requested format.

Example Response:

{
  "SOPClassUID": "1.2.840.10008.5.1.4.1.1.12.1",
  "SOPInstanceUID": "1.3.12.2.1107.5.4.3.321890.19960124.162922.29",
  "StudyDate": "19941013",
  "StudyTime": "141917",
  "Modality": "XA",
  "LossyImageCompressionRetired": "01",
  "PatientName": "Rubo DEMO",
  "PatientID": "556342B",
  "PatientBirthDate": "19951025",
  "PatientSex": "M",
  "FrameTime": "33",
  "RadiationSetting": "GR",
  "PositionerPrimaryAngle": "-32",
  "PositionerSecondaryAngle": "2",
  "StudyInstanceUID": "1.3.12.2.1107.5.4.3.123456789012345.19950922.121803.6",
  "SeriesInstanceUID": "1.3.12.2.1107.5.4.3.123456789012345.19950922.121803.8",
  "SeriesNumber": "1",
  "SamplesPerPixel": "1",
  "PhotometricInterpretation": "MONOCHROME2",
  "NumberOfFrames": "96",
  "FrameIncrementPointer": "(0018,1063)",
  "Rows": "512",
  "Columns": "512",
  "BitsAllocated": "8",
  "BitsStored": "8",
  "HighBit": "7",
  "PixelIntensityRelationship": "LIN",
  "RecommendedViewingMode": "NAT",
  "RWavePointer": "[20, 53, 77]",
  "PixelData": "b'\\xfe\\xff\\x00\\xe0\\x80\\x01\\x00\\x00\\x00.....",
  "ImageFormat": "PNG",
  "Images": ["iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAAAAADRE4s...", "d...", ""]
}

Explanation of Response Fields:

• ImageType: Describes the type of image (e.g., derived, primary).

• SOPClassUID: The unique identifier for the DICOM SOP class.

• SOPInstanceUID: The unique identifier for the specific instance of the DICOM image.

• PatientName: Name of the patient.

• Modality: Type of medical imaging modality used (e.g., XA for X-ray angiography).

• PixelData: The pixel data of the image (in binary format).

• ImageFormat: The format of the image returned (e.g., PNG).

• Images: A list of base64-encoded image data for each image.

2. DICOM File Generation and Download

This endpoint allows generating a DICOM file from provided metadata and an image file.

Endpoint

• URL: /api/dicom/generate/

• Method: POST

• Description: Allows users to upload an image and provide necessary DICOM metadata to generate a valid DICOM file.

Request

• Headers: - Authorization: ApiKey your_api_key_here - Content-Type: multipart/form-data

• Body Parameters: - file_name (required): The name of the generated DICOM file (without extension). - image (required): The image file to be embedded in the DICOM file. Supported formats: png, jpeg. - Additional DICOM metadata fields (optional): Key-value pairs of metadata fields to be included in the DICOM file.

Example Request:

POST /api/dicom/generate/ HTTP/1.1
Host: localhost:8080
Authorization: ApiKey amRqSgZZ...
Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name="file_name"

example_dicom
--boundary
Content-Disposition: form-data; name="image"; filename="image.png"
Content-Type: image/png

<binary image file content>

--boundary
Content-Disposition: form-data; name="PatientName"

John Doe
--boundary
Content-Disposition: form-data; name="Modality"

CT
--boundary--

Response

If the request is successful, the server will return a downloadable DICOM file.

Example Response Headers:

HTTP/1.1 200 OK
Content-Type: application/dicom
Content-Disposition: attachment; filename="example_dicom.dcm"

The response body will contain the binary content of the generated DICOM file.

API Usage Limits

Each developer has access to the DICOM file upload endpoint up to 1000 times per month. To check your remaining usage, you can use the following endpoint:

To view the daily and monthly usage for your developer profile, send a GET request to the activity-summary endpoint.

Endpoint - URL: api/developer/profiles/activity-summary/ - Method: GET - Description: Retrieves the daily and monthly usage statistics for your API access.

• Headers:

  • Authorization: Bearer <access_token>

GET /api/developer/profiles/activity-summary/ HTTP/1.1
Host: localhost:8080
Authorization: Bearer <access_token>

You will receive a response with your daily and monthly usage:

{
  "daily_activity": [
    {
      "day": "2025-01-05",
      "count": 1
    }
  ],
  "monthly_total": 1
}

• daily_activity: An array showing how many requests have been made each day.

• monthly_total: The total number of requests made for the current month.

Error Handling: API Limit Exceeded

If the monthly usage limit is exceeded, you will receive a 429 Too Many Requests response. The response will contain an error message indicating that the limit has been reached, and you will need to wait until the new month to refresh your quota.

Example Response for Exceeded Limit:

{
  "error": "Monthly API request for '/api/dicom/read/file/' limit exceeded.",
  "quota": 1000,
  "requests_used": 1001
}

• error: A description of the error, including the endpoint and the exceeded limit.

• quota: The maximum number of requests allowed per month for that endpoint.

• requests_used: The number of requests that have been used during the current month.

Once the limit is reached, you will need to wait for the start of the new month for your API request quota to reset.