Iris RESTful Server for WSI Delivery

Updated 8 July 2026

Iris RESTful Server is a RESTful microservice that delivers high-resolution whole slide images from IFE files by streaming tiles on demand.
The architecture employs a dual-stack design with Boost Beast HTTP and asynchronous file access to achieve efficient, lockless tile retrieval and metadata handling.
The server supports both a native Iris RESTful API and a DICOMweb WADO-RS interface, ensuring seamless integration with OpenSeaDragon viewers and clinical systems.

The Iris RESTful Server is a low-overhead HTTP server for whole slide image (WSI) delivery from the Iris File Extension (IFE), a low overhead performance-oriented WSI file format designed to improve the image rendering experience for pathologists and simplify image management for system administrators. It was developed to address a specific limitation of static hypertext transfer protocol (HTTP) file servers: they cannot natively stream subregions of high-resolution image files such as the IFE, even though the majority of contemporary WSI viewer systems are browser-based web applications that leverage OpenSeaDragon as the tile-based rendering framework. In place of the prevalent workflow of converting WSI files to Deep Zoom Images (DZI) for compatibility with simple static HTTP file servers, the server exposes a RESTful API natively compatible with the DICOMweb WADO-RS API, and testing shows that a single instance can handle over 5000 tile requests per second with a median latency of 21 ms on a private network (Landvater et al., 8 Aug 2025).

1. Problem setting and rationale

The server is motivated by the mismatch between high-resolution pathology imaging and conventional static web delivery. Static HTTP/DZI workflows impose three costs identified in the system description: file system overload, because DZI conversion creates thousands of tile files and subdirectories per slide; metadata loss and conversion overhead, because converting from proprietary or DICOM image formats to DZI is slow and can strip clinical metadata; and inefficiency, because static servers do not natively support subregion streaming or API-driven tile retrieval, while partial reads via HTTP Range are described as more complex and less efficient (Landvater et al., 8 Aug 2025).

The Iris RESTful Server addresses these constraints by serving tiles and metadata directly from a single IFE slide file. No tile pre-generation is required; tiles are read and streamed on demand; and file-format preservation avoids data loss from conversion. The resulting workflow is described as cleaner for slide management, backup, and security. A recurrent misconception is that DZI conversion is an unavoidable prerequisite for browser-based WSI viewing. The system is explicitly presented as a counterexample: contemporary OpenSeaDragon-based viewers can consume IFE-backed tiles through the Iris RESTful API, eliminating the intermediate DZI representation (Landvater et al., 8 Aug 2025).

2. Internal architecture and implementation model

The implementation is written in C++ with Boost Beast HTTP and Asio networking libraries atop the public IFE libraries. Its architecture is organized around two independent stacks. The networking stack is based on Boost Beast HTTP and Asio and is dedicated to swiftly processing network packets and maintaining connection reliability. The file system stack is independently multitasked, handling slide access, validation, and tile production in a lockless, reference-counted manner; slides are memory-mapped and served while referenced (Landvater et al., 8 Aug 2025).

This separation of concerns is central to the server’s design philosophy. The system is described as performance-oriented, security-centric, interoperable, and simple to integrate into existing WSI viewers. It is also packaged as Docker containers for scalable, orchestration-friendly deployment on Kubernetes, ECS, or Cloud Run, while remaining runnable as a standalone server or in simple Docker setups. The server is further characterized as a cross-origin resource sharing (CORS) microservice intended to separate IMS/PACS systems and viewer applications from the slide-serving infrastructure. This suggests an architectural preference for narrowly scoped, composable services rather than monolithic viewer-storage bundles (Landvater et al., 8 Aug 2025).

3. API surface and standards interoperability

The server exposes both a custom Iris RESTful API and a DICOMweb WADO-RS-compatible interface. The supported endpoints are given as follows (Landvater et al., 8 Aug 2025):

GET <server>/slides/<slide-name>/metadata
GET <server>/slides/<slide-name>/layers/<layer>/tiles/<tile>

GET <server>/studies/<study>/series/<UID>/metadata
GET <server>/studies/<study>/series/<UID>/instances/<layer>/frames/<tile>

The first pair provides slide metadata in JSON and compressed tile delivery through the Iris RESTful API. The second pair provides DICOMweb WADO-RS access for study, series, and frame-oriented navigation. Strict validation of API calls is enforced for security. Native support for both interfaces is significant because it combines a viewer-oriented tile API with out-of-the-box compatibility for clinical systems and standards, rather than requiring a choice between viewer integration and DICOM interoperability (Landvater et al., 8 Aug 2025).

The paper also provides a tile-indexing formula:

$t = y \times tiles_{l,x} + x$

where $t$ is the tile index at $x, y$ of layer $l$ , and $tiles_{l,x}$ is total tiles in $x$ for layer $l$ (Landvater et al., 8 Aug 2025). In context, this formalizes how spatial tile coordinates are mapped to the server’s tile addressing scheme.

4. Performance characteristics

Performance evaluation is one of the central technical claims of the system. Testing used Locust load testing with 160–220 concurrent users and 1–2 ms per tile request, and the results are reported for both private and public deployments as well as comparator services (Landvater et al., 8 Aug 2025).

Deployment	Performance	Environment
Iris Private	3883–5061 requests/s; 21 ms median; 63 ms 95%ile	Turing RTK1 (8c, $200 SBC)
Iris Example (AWS)	1241–1944 requests/s; 59 ms median; 120 ms 95%ile	Fargate 1vCPU
Path-Presenter (DZI)	987–1560 requests/s; 79 ms median; 160 ms 95%ile	Public instance
Slim (DICOMweb)	114–146 requests/s; 650 ms median; 2.3 sec 95%ile	Public instance

These figures support the claim that the server targets very high tile request throughput with low latency even on modest hardware. They also clarify a second common misconception: DICOMweb compatibility need not imply a purely enterprise-oriented, latency-heavy stack. The Iris implementation is described as natively compatible with DICOMweb WADO-RS while simultaneously operating as a low-overhead tile server for browser viewers (Landvater et al., 8 Aug 2025).

5. Security, access control, and deployment model

Security is treated as a first-class property rather than an add-on. The server enforces strict API call validation, reduces attack surface by limiting file-serving scope, and defaults to end-to-end TLS encryption with auto-generated self-signed RSA certificates. Only well-formed, standards-compliant API requests are accepted. In static server mode, it is impossible to download raw slide files directly, and only permitted static files are allowed (Landvater et al., 8 Aug 2025).

CORS behavior is configurable for single-domain, multidomain, or wildcard origins, and CORS can be disabled when the server also provides the viewer application. Containerization is described as a way to isolate the microservice and support deployment best practices. The deployment options span one-line Docker execution, simple standalone use, and scalable orchestration behind a load balancer; the paper explicitly suggests Kubernetes-style deployment as a scalable, stateless microservice for institutions. Automated builds and vulnerability scans are reported as showing zero critical vulnerabilities (Landvater et al., 8 Aug 2025).

The public example domain, https://examples.restful.irisdigitalpathology.org, is provided as a development tool to accelerate WSI web viewer development. This operational detail reinforces that the server is intended not only as a backend component but also as a reference platform for integration testing and viewer prototyping (Landvater et al., 8 Aug 2025).

6. OpenSeaDragon integration and replacement of DZI workflows

A major practical component of the system is IrisTileSource, a new OpenSeaDragon TileSource subclass compatible with the Iris RESTful API and merged into the next OpenSeaDragon release. The integration is described as a simple and immediate drop-in replacement of DZI images within WSI viewer stacks. The stated migration procedure is minimal: replace only four lines of viewer JavaScript code to switch from DZI tileSources to Iris; the serverUrl and slideId point to the Iris RESTful server and IFE-encoded file; and OpenSeaDragon automatically queries metadata and fetches tiles via the Iris RESTful API (Landvater et al., 8 Aug 2025).

This workflow change matters because it turns the server from a standalone delivery component into an interoperability layer for existing viewers. Rather than redesigning viewer logic, an existing OpenSeaDragon stack can retain its tile-based rendering model while replacing the backing storage and delivery path. The consequence is that DZI file proliferation, separate conversion pipelines, and corresponding metadata losses can be removed without abandoning established viewer infrastructure. In that sense, IrisTileSource operationalizes the server’s broader claim: direct HTTP access to IFE-backed image regions can function as a browser-native alternative to static HTTP plus pre-rendered tile pyramids (Landvater et al., 8 Aug 2025).

7. Position within RESTful server research

Within the broader literature on RESTful servers, the Iris RESTful Server occupies a specialized position: low-latency, standards-aware streaming of subregions from high-resolution scientific image files. Other RESTful systems in the provided literature emphasize different concerns. HTTP Mailbox describes asynchronous RESTful communication through a store-and-forward message broker with support for a full range of HTTP methods, multicast, and broadcast semantics (Alam et al., 2013). MCP Bridge describes a lightweight, LLM-agnostic RESTful proxy with risk-based execution over MCP servers (Ahmadi et al., 11 Apr 2025). EasyMLServe separates model logic, REST server, and optional GUIs for machine learning services (Neumann et al., 2022). COTS presents a model-driven approach for testing RESTful applications using a session-type-inspired DSL and randomized model-based executions (Burlò et al., 2024).

These systems clarify what Iris is and is not. It is not a store-and-forward broker, not a tool-execution proxy, and not a generic ML-serving framework. Instead, it is a domain-specific RESTful microservice optimized for WSI tile and metadata streaming, with DICOMweb interoperability and direct viewer integration. At the same time, a plausible implication is that Iris shares with these systems several broader REST design patterns: decoupling infrastructure components via narrow APIs, exposing resource-oriented endpoints, and separating client concerns from backend execution environments. Another plausible implication is that protocol-oriented testing methodologies such as COTS could be relevant for future validation of the Iris API surface, although such a testing stack is not described as part of the Iris implementation itself (Landvater et al., 8 Aug 2025).