IMAGING CONNECTORS

Best Practices / APIs & SDK / Next Steps

8 of 8

Implementation guidance, API reference patterns, SDK examples and operational best practices for reliable, secure and performant Mediloop imaging integrations.

DICOMDICOMwebFHIR ImagingRIS / MWLPACS / VNAWorkflowsSecuritySDK

End-to-End Imaging Integration Flow

Imaging order

Order created in HIS / EHR or API

RIS / Worklist

Accession + DICOM MWL

Acquisition

Images acquired, MPPS returned

PACS / VNA

Images stored and indexed

Query study

QIDO-RS / C-FIND

Retrieve & view

WADO-RS / streaming

Report & data

SR / FHIR / measurements

Audit & track

Access, events and provenance

Connector Options

Option	Best for	Examples
DICOM Classic	Pixel data and legacy imaging workflows	C-FIND, C-MOVE, C-GET, C-STORE, C-ECHO, MWL, MPPS
DICOMweb	Modern HTTP-based imaging	QIDO-RS, WADO-RS, STOW-RS
FHIR Imaging	Metadata, reports and workflows	ImagingStudy, DiagnosticReport, Observation, Task, Appointment
HL7 v2	RIS / report integration	ORM, ORU, OML, SIU, ACK

Required Capabilities

Query / discover studies and worklists

Retrieve and stream images efficiently

Store images and derived objects

Modality worklist and MPPS

Report exchange — SR / FHIR / HL7

Event notifications and subscriptions

Security, audit and access control

High availability and failover

Standards compliance and validation

Authentication & Scopes

OAuth 2.1 / OpenID Connect

mTLS for service-to-service calls

JWT access tokens with short lifetimes

Role and tenant context for every operation

imaging:readimaging:writeimaging:study:readimaging:study:writeimaging:worklist:readimaging:report:readimaging:report:writeimaging:event:read

System Configuration

PACS / VNA

AE Title, host, port, TLS, timeout, max PDU, compression

RIS

MWL AE Title / base URL, MPPS and accession mapping

Orthanc / gateway

DICOMweb gateway, plugins, retention and export rules

Time & localization

UTC storage, NTP synchronization and timezone presentation

Imaging APIs Quick Reference

Purpose	DICOM Classic	DICOMweb (HTTP)	FHIR (R4/R4B)	Notes
Connectivity test	C-ECHO	GET /ping or health endpoint	N/A	Verify availability
Query studies	C-FIND (Study Root)	GET /studies	GET /ImagingStudy	Use filters
Query worklist	C-FIND (MWL)	Gateway-specific worklist route	GET /Task or /ServiceRequest	RIS / Modality workflow
Retrieve instance	C-MOVE / C-GET	GET /studies/{id}/series/{id}/instances/{id}	N/A	Prefer WADO-RS
Store instance	C-STORE	POST /studies (STOW-RS)	N/A	Upload / ingest
Reports	DICOM SR	WADO-RS for SR	GET /DiagnosticReport	FHIR / HL7 supported
Subscriptions / events	N/A	Webhook / SSE	POST /Subscription	Event-driven integrations

Event & Webhook Subscriptions

Event	Description
imaging.study.created	New study available
imaging.study.updated	Study metadata updated
imaging.instance.created	New instance stored
imaging.instance.deleted	Instance removed according to policy
imaging.report.finalized	Report finalized
imaging.report.amended	Report amended
imaging.worklist.updated	Worklist item updated
imaging.mpps.updated	MPPS status updated
imaging.storage.warning	Storage threshold or archive warning

TypeScript SDK Examples

Initialize SDK

typescriptCopy

import { ImagingClient } from '@mediloop/imaging-sdk';

const client = new ImagingClient({
  baseUrl: 'https://api.mediloop.com/v1',
  auth: { type: 'oauth2', clientId: process.env.CLIENT_ID!, clientSecret: process.env.CLIENT_SECRET! },
  scopes: ['imaging:read', 'imaging:report:read']
});

Query studies

typescriptCopy

const studies = await client.studies.search({
  patientId: '12345',
  modality: 'CT',
  dateFrom: '2026-08-01',
  limit: 20,
});

Retrieve instances

typescriptCopy

const stream = await client.instances.getInstanceStream({
  studyInstanceUID,
  seriesInstanceUID,
  sopInstanceUID,
  accept: 'application/dicom'
});
viewer.loadStream(stream);

Get report

typescriptCopy

const report = await client.fhir.getDiagnosticReport(reportId);
console.log(report.status, report.conclusion);

Subscribe to events

typescriptCopy

client.events.subscribe(['imaging.study.created','imaging.report.finalized'], event => {
  console.log(event.type, event.resourceId);
});

Upload (STOW-RS)

typescriptCopy

await client.instances.store({
  file: dicomFileStream,
  studyInstanceUID,
  seriesInstanceUID,
});

Error Handling

Use standard HTTP status codes for REST / DICOMweb

Map DICOM status and DIMSE errors

Retry transient failures with exponential backoff

Use idempotency for replay-safe operations

Handle partial study transfers gracefully

Log correlation IDs for every request

Performance & Scalability

Prefer WADO-RS for viewer streaming

Enable HTTP/2 and keep-alive

Use range requests for large objects

Generate thumbnails / key-image caches

Parallelize retrieval with concurrency limits

Read from closest archive / edge cache where appropriate

Monitor queue depth, latency and throughput

PACS / VNA Best Practices

Use dedicated and documented integration AE Titles

Enable compression where clinically and technically appropriate

Configure storage commitment and verification

Set retention and disaster-recovery policies

Monitor queue, errors and storage usage

Test failover and recovery scenarios

Keep vendor conformance statements and endpoint inventories current

Limits & Quotas

Resource	Example default limit
Studies query	100 per request
Instances retrieval	1,000 per request / batch policy
STOW-RS upload	5 GB per request subject to deployment policy
Report size	50 MB
API rate limit	120 requests / minute example only

Limits shown in documentation are illustrative until matched to implemented backend contracts and deployment tiers.

SDK & Tooling

TypeScript / Node.js imaging SDK

Postman collection

DICOM test suite such as dcm4che tooling

Orthanc Web UI for local development / validation

Mediloop sandbox

CLI tools where available

Next Steps

Sandbox access

Request credentials and test connectors

Connect systems

Configure PACS / RIS / modalities

Validate workflow

Test end-to-end scenarios

Go live

Enable production monitoring

Optimize & scale

Tune performance and caching

Explore AI & analytics

Use governed imaging data for advanced workflows