Introduction
This article describes performance tuning considerations for the Domino REST API (DRAPI) β the modern, open-source REST interface for HCL Domino.
For an overview of DRAPI, see the official project documentation:
Domino has supported HTTP access and various web and REST integration approaches for decades, including classic Domino HTTP, XPages, custom servlets, and other application-specific implementations. This guide focuses specifically on tuning DRAPI workloads and is not intended as general guidance for classic Domino HTTP or other legacy REST implementations.
As organizations modernize their application ecosystems, Domino can serve as a backend platform for web applications, mobile clients, integration platforms, automation tools, and other enterprise applications through DRAPI.
High volumes of short-lived, concurrent API requests introduce specific considerations around resource management, database access, view indexing, and DRAPI runtime configuration. This guide covers the primary architectural and operational considerations for deploying Domino in high-concurrency DRAPI environments.
Understanding DRAPI Workloads
DRAPI workloads can have characteristics that differ from traditional Notes client workloads:
β Short-Lived Requests: High volumes of relatively short HTTP/API operations.
β Read-Heavy Patterns: Frequent retrieval and JSON serialization of Domino documents.
β Concurrent Traffic: Simultaneous access from web applications, integrations, automation tools, and other clients.
These workloads can place pressure on several server resources:
β DRAPI worker pool and Vert.x runtime
β NSF Buffer Pool
β View indexes and database I/O
β CPU and memory
β Storage and network resources
Performance tuning should therefore be based on measurements from the actual workload rather than applying a fixed configuration to every environment.
Key Performance and Infrastructure Optimization
1. Domino Memory Management β NSF Buffer Pool
The NSF Buffer Pool is an important component of Domino database performance.
The buffer pool caches database pages in memory, reducing physical disk reads for frequently accessed data and potentially improving database response times.
Domino normally calculates the appropriate buffer pool allocation automatically based on available system resources. For most environments, administrators should allow Domino to manage this automatically unless performance analysis indicates that manual tuning is required.
Example: NSF Buffer Pool Configuration
If performance analysis indicates that manual tuning is appropriate, the buffer pool can be explicitly configured using the following NOTES.INI parameter:
ξ° NSF_Buffer_Pool_Size_MB=2048
ξ° The value above is an example configuration value, not a universal recommendation. The appropriate value depends on available physical memory, database workload, DRAPI concurrency, JVM requirements, operating-system requirements, and other Domino processes.
Before changing the buffer pool configuration:
β Measure current memory utilization.
β Review buffer pool statistics.
β Monitor database read/cache behavior.
β Review CPU and disk I/O.
β Monitor DRAPI response times.
β Verify sufficient physical memory is available.
β Test the change in a non-production environment.
Avoid increasing the buffer pool without considering the memory requirements of the complete Domino environment.
For Domino system requirements:
For additional information about Domino database and buffer pool performance:
2. View Index Performance
DRAPI-backed applications commonly rely on Domino views for data retrieval. Efficient view design can have a significant effect on API response time, particularly for frequently accessed data.
Recommended practices include:
β Keep views focused on the data required by the application.
β Avoid unnecessary columns and expensive formulas.
β Use appropriate selection formulas and indexing strategies.
β Avoid unnecessarily large or complex views.
β Archive historical data where appropriate.
β Review frequently accessed views for unnecessary index rebuilding or refreshing.
Common View Performance Considerations
Examples of view designs that can create additional indexing or evaluation overhead include:
β Time-dependent formulas such as @Today, @Now, or @Hour(@Now).
β Deeply categorized views with multiple levels of categorization.
β Complex @Functions or large formula blocks in selection formulas.
β Views that require frequent index rebuilding or refreshing.
Time-dependent formulas deserve particular attention because their results can change as time passes, potentially causing a view to become out of date.
Where appropriate, applications can pre-compute values such as date buckets or status flags into document fields and index those fields instead of relying on time-dependent formulas.
For views that must use time-dependent logic, evaluate the appropriate view refresh configuration and its effect on the workload.
Frequently Accessed Views
There is no general Domino setting that simply keeps selected view indexes permanently in memory for DRAPI.
Instead, developers should focus on efficient view design and access patterns. Frequently used views should be designed so they can be accessed efficiently without repeatedly triggering expensive index rebuilding or refreshing.
3. DRAPI Worker Pool and Concurrency Settings
DRAPI runs on a Vert.x-based runtime with its own worker-pool and concurrency controls, separate from the traditional Domino HTTP thread configuration used by classic Domino HTTP.
DRAPI configuration parameters are documented here:
Depending on the DRAPI version and configuration, relevant parameters can include:
β vertx.workerPoolSize β controls the worker threads available for blocking operations.
β vertx.maxEventLoopExecuteTime β controls the threshold used by Vert.x to identify potentially blocked event-loop processing.
β concurrentRequestMaxCount β controls the maximum number of concurrent requests allowed to Domino core.
β concurrentRequestDelay β controls request delay behavior when concurrency limits are reached.
β concurrentRequestRetries β controls retry behavior when requests cannot immediately be processed.
β Verticle configuration β controls instances and thread allocation for specific API components.
The exact parameters and default values depend on the DRAPI release and configuration. Administrators should consult the documentation for the specific DRAPI version being deployed rather than applying values from another release.
Tuning Approach
Increasing concurrency settings does not automatically improve performance.
Before changing these parameters, evaluate:
β Peak concurrent requests.
β Average and maximum API response time.
β CPU utilization.
β JVM and system memory.
β Database access time.
β Disk I/O.
β DRAPI worker-pool utilization.
β Error and timeout rates.
Changes should be tested under a representative workload and compared with the original configuration.
A healthy configuration should maintain stable response times without sustained CPU, memory, worker-pool, or database-resource saturation.
4. Database Maintenance
Maintaining healthy database structures is important for predictable DRAPI performance.
Use DBMT (Database Maintenance Tool) as the primary mechanism for routine database maintenance. DBMT can coordinate database maintenance activities including compact and view-update operations.
Configure DBMT through a Program document and/or supported configuration options rather than routinely scheduling separate Updall and Compact tasks when DBMT is already configured to perform those activities.
Typical DBMT options include:
β -compactThreads
β -updallThreads
β -range
β -compactNdays
β -force
Administrators should configure these options according to their Domino environment and maintenance requirements.
For information about configuring DBMT through a Program document:
Fixup
Fixup should not be treated as routine replacement for DBMT.
Use Fixup when there is a specific database integrity or maintenance requirement, following the organizationβs operational procedures and applicable HCL guidance.
Scheduling
Where possible, schedule database maintenance during periods of lower application activity.
This reduces the possibility that maintenance operations will compete with peak DRAPI traffic for CPU, memory, and disk resources.
Monitoring and Server Statistics
Performance optimization should be guided by measured data rather than assumptions.
For DRAPI workloads, administrators should distinguish DRAPI statistics from statistics associated with classic Domino HTTP.
DRAPI-related statistics use the RestAPI.* namespace, whereas traditional HTTP.* statistics relate to classic Domino HTTP processing.
Use the Domino console command:
ξ° show stat
ξ° to review relevant Domino statistics.
Important areas to monitor include:
β Database buffer pool statistics.
β Database read/cache behavior.
β RestAPI.* statistics applicable to the deployed DRAPI version.
β Platform memory statistics.
β Platform system statistics.
β CPU utilization.
β Disk I/O.
β Network utilization.
β API response times.
β Request and error rates.
The exact RestAPI.* statistics available can vary depending on the DRAPI release and configuration. Administrators should consult the documentation for the deployed version when selecting specific metrics.
Where enabled and supported by the deployed DRAPI version, Prometheus metrics can provide additional monitoring capabilities.
The important practice is to establish a baseline before making changes and compare the same measurements after tuning.
Enterprise Infrastructure Architecture
A well-performing DRAPI environment depends on the complete application and infrastructure architecture, not only on individual Domino settings.
Important considerations include:
β Adequate physical memory.
β Fast SSD or NVMe storage where appropriate.
β Sufficient CPU capacity for the expected workload.
β Reliable and sufficiently provisioned network connectivity.
β Reverse proxy or load balancer where required.
β TLS configuration and termination strategy.
β Monitoring and alerting.
β Regular backups.
For environments requiring higher availability or greater request capacity, multiple Domino servers behind a load balancer can be considered, depending on the application architecture, workload, and session/state requirements.
Infrastructure sizing should be based on measured workload characteristics rather than a fixed hardware configuration.
Performance Tuning Approach
A repeatable performance-tuning process is more effective than changing multiple settings simultaneously.
1. Establish a Baseline
Measure:
β DRAPI request volume.
β Concurrent requests.
β Response times.
β Error and timeout rates.
β CPU and memory utilization.
β Database and disk performance.
2. Identify the Bottleneck
Determine whether the limitation is primarily related to:
β DRAPI concurrency.
β Database access.
β View indexing.
β Memory.
β CPU.
β Disk I/O.
β Network latency.
β Application design.
3. Change One Area at a Time
Avoid changing multiple major configuration parameters simultaneously.
This makes it easier to determine whether a specific change actually improves the workload.
4. Load Test
Use a representative workload that reflects expected production request patterns.
5. Compare Results
Compare the same measurements before and after the change.
6. Document the Configuration
Record the tested configuration, workload characteristics, observed results, and rollback procedure.
Checklist: Best Practices Summary
- Maintain Updates: Keep Domino and DRAPI updated with supported maintenance releases and fixes.
- Optimize Views: Design efficient views for DRAPI access and avoid unnecessary complexity, particularly time-dependent formulas and excessive categorization.
- Manage Memory Carefully: Allow Domino to manage the NSF Buffer Pool unless measurements justify manual tuning.
- Use DRAPI Configuration: Review DRAPI worker-pool and concurrency settings using the official documentation for the deployed version.
- Use DBMT: Use DBMT as the primary routine database maintenance mechanism rather than scheduling separate Updall and Compact tasks unnecessarily.
- Use Fixup Selectively: Apply Fixup for specific database integrity or maintenance requirements rather than as routine maintenance.
- Monitor DRAPI Metrics: Monitor applicable RestAPI.* statistics together with core Domino and operating-system metrics.
- Benchmark Changes: Establish a baseline and measure the effect of configuration or application changes.
- Test Before Production: Validate tuning changes under representative workload conditions before applying them to production.
- Plan for Scale: For larger environments, consider load balancing and multiple Domino servers where appropriate to the application architecture.
Conclusion
High-concurrency DRAPI performance depends on the interaction between DRAPI configuration, Domino database design, view indexes, available resources, and application architecture.
The most effective tuning approach is to establish a performance baseline, identify the actual bottleneck, make controlled changes, and measure the results. DRAPI-specific configuration and monitoring, combined with sound Domino database and application design, can help maintain predictable performance as API workloads increase.