web sdk performance guide

Optimizing Web SDK performance

This guide provides strategies for optimizing your Web SDK integration. Following these recommendations will improve response times, reduce server load, and create a more efficient application.

Response Format Optimization

Use JSON Format

Always use text/json for optimal performance.

The Web SDK supports both JSON and XML, but JSON provides significantly better performance:

Format	Accept Header	Performance Impact
JSON	text/json	✅ Fastest - Recommended
JSON (legacy)	application/json	Slower - For SC 5.7 compatibility
XML	text/xml	Slower - Only when required
XML (legacy)	application/xml	Slower - For SC 5.7 compatibility
Default	*/*	Slowest - Uses XML

Example:

GET /entity?q=entity={guid},Name,Description
Accept: text/json

Performance gain: JSON responses are typically 30-40% smaller and parse faster than XML.

Field Projection

Request Only What You Need

Problem: Retrieving all entity properties wastes bandwidth and processing time.

Solution: Use field projection to specify exactly which properties you need.

Comparison

Inefficient (retrieves all properties):

GET /entity/{cardholder-guid}

Efficient (retrieves only needed properties):

GET /entity?q=entity={cardholder-guid},FirstName,LastName,EmailAddress,MobilePhoneNumber

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "FirstName": "Patricia",
      "LastName": "Lynch",
      "EmailAddress": "Lea66@hotmail.com",
      "MobilePhoneNumber": "995-870-2733"
    }
  }
}

Performance gain: Reduces response size by 70-90% in typical scenarios.

When to Use Full Entity Retrieval

Use /entity/{guid} only when:

• You need all properties
• Exploring entity structure during development
• Creating complete backups

Batch Operations

Read Multiple Entities in One Request

Problem: Making separate requests for each entity causes network overhead.

Solution: Batch multiple entity queries into a single request.

Reading Multiple Entities

Inefficient (3 separate requests):

GET /entity?q=entity={cardholder1},FirstName,LastName
GET /entity?q=entity={cardholder2},FirstName,LastName
GET /entity?q=entity={cardholder3},FirstName,LastName

Efficient (1 batched request):

GET /entity?q=entity={cardholder1},FirstName,LastName,entity={cardholder2},FirstName,LastName,entity={cardholder3},FirstName,LastName

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      {
        "FirstName": "Patricia",
        "LastName": "Lynch"
      },
      {
        "FirstName": "Carson",
        "LastName": "Jones"
      },
      {
        "FirstName": "Philip",
        "LastName": "Weissnat"
      }
    ]
  }
}

Performance gain: Reduces network round-trips by 66% (1 request vs 3).

Batch Different Entity Types

You can query different entity types in the same request:

GET /entity?q=entity={cardholder},FirstName,LastName,EmailAddress,entity={credential},Name,ActivationDate,State

Response:

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      {
        "FirstName": "Adrienne",
        "LastName": "Rowe",
        "EmailAddress": "adrienne.rowe@yahoo.com"
      },
      {
        "Name": "Adrienne Rowe Credential",
        "ActivationDate": "2023-07-15T04:31:00.307Z",
        "State": "Active"
      }
    ]
  }
}

Updating Multiple Entities

Efficient batch update:

POST /entity?q=entity={cardholder1},EmailAddress=new1@example.com,entity={cardholder2},EmailAddress=new2@example.com,entity={cardholder3},EmailAddress=new3@example.com

Benefits:

• Reduces network overhead
• Minimizes latency
• Improves server resource utilization
• Reduces serialization overhead
• Increases throughput

Limitation: Query string length limits.

Session Management

Understanding and optimizing session management is critical for Web SDK performance. For detailed session architecture and authentication, see the Getting Started Guide.

How Sessions Work

When you make your first authenticated request, the Web SDK creates a session that:

• Establishes a connection to Security Center
• Caches queried entities in memory
• Stores session-specific settings (like /creationpartition)
• Tracks event subscriptions

Session Lifecycle

Event	Behavior	Impact
First request	Session created	Initial overhead (~200-500ms)
Subsequent requests	Session reused	Fast (~10-50ms)
5 minutes of inactivity	Session expires	Next request recreates session
Any API call	Resets 5-minute timer	Keeps session alive
Event subscription active	Auto keep-alive every 1 minute	Session never expires

Session Timeout Impact

Scenario: Session expires between requests

Cost of session recreation:

• Reconnect to Security Center (~100-200ms)
• Re-authenticate user (~50-100ms)
• Rebuild entity cache (~50-200ms)
• Total overhead: ~200-500ms per recreated session

Solution: Keep sessions alive.

Keep-Alive Strategies

Strategy 1: Periodic Ping (Simple Applications)

Send a lightweight request every 4 minutes to keep the session alive:

GET /
Accept: text/json

Pros:

• Simple to implement
• Works for any application
• Low overhead

Cons:

• Background thread/timer required
• Small network overhead every 4 minutes

Strategy 2: Event Subscription (Real-Time Applications)

Subscribe to events to enable automatic keep-alive (every 1 minute):

GET /events/subscribe?q=event({entity-type},{event-type})

Benefits:

• Automatic keep-alive built-in
• No manual timer needed
• Session never expires while subscribed
• Also provides real-time event stream

Best for: Applications that need real-time updates or run continuously.

Strategy 3: On-Demand (Short-Lived Applications)

For scripts or short-lived applications, accept session recreation overhead:

Best for:

• Cron jobs
• One-time scripts
• Applications that run < 5 minutes

Cost: ~200-500ms initial connection time per execution.

Session Isolation

Recommendation: Use one Security Center user account per application.

Why:

• Sessions are shared by username + application ID
• Separate users = separate sessions = separate caches
• Prevents cache duplication
• Easier to manage

Example architecture:

Application A → user_app_a@example.com → Session A → Cache A
Application B → user_app_b@example.com → Session B → Cache B
Application C → user_app_c@example.com → Session C → Cache C

Session-Specific Settings

Critical: Some settings are session-scoped and lost when sessions expire:

• /creationpartition/{partitionIds} - Default partition for entity creation
• Entity cache contents
• Event subscriptions

Best practice:

• Call /creationpartition before creating entities (don't assume it persists)
• Re-subscribe to events if session was recreated
• Implement session detection in your application

Cache Strategies

The Web SDK maintains an in-memory entity cache per session. Understanding and leveraging this cache is crucial for performance.

How the Cache Works

First request for an entity:

1. Web SDK receives request
2. Queries Security Center Directory
3. Loads entity data
4. Stores in cache
5. Returns to client Time: ~50-200ms

Subsequent requests for same entity (cache hit):

1. Web SDK receives request
2. Returns from cache
3. No Directory query needed Time: ~5-20ms

Performance gain: 10-40x faster for cached entities.

Cache Warming with DownloadAllRelatedData

For operations that will access many entities, pre-load the cache:

GET /report/CardholderConfiguration?q=DownloadAllRelatedData=true,Page=1,PageSize=1000

What happens:

• Retrieves cardholder GUIDs
• Loads complete entity data for all cardholders into cache
• Subsequent /entity requests for those cardholders are fast (cache hits)

Example workflow:

# Step 1: Warm cache (loads 1000 cardholders)
GET /report/CardholderConfiguration?q=DownloadAllRelatedData=true,Page=1,PageSize=1000

# Step 2: Query specific cardholders (served from cache - FAST)
GET /entity?q=entity={cardholder1},FirstName,LastName,entity={cardholder2},FirstName,LastName

Performance gain: Steps 2+ are 10-40x faster.

When to Use DownloadAllRelatedData

Use when:

• Bulk operations on many entities
• Exporting data
• Generating reports
• Processing large batches

Don't use when:

• Querying single entities
• Only need GUID list (not full entity data)
• Memory constrained environments
• Session likely to expire before using cached data

Cache Scope

What's cached per session:

• Entity data loaded via /entity queries
• Entities loaded via DownloadAllRelatedData=true
• Related entities automatically loaded with main entity

What's NOT cached:

• Report results (/report endpoints)
• Event stream data

Basic Entity Properties

If you only need basic entity information, don't use DownloadAllRelatedData=true:

Basic properties available without full entity load:

• Guid
• Name
• Description
• EntityType
• LogicalId
• CreatedOn
• IsOnline
• CustomFields (metadata only)

Example (efficient for basic info):

GET /report/CardholderConfiguration?q=Page=1,PageSize=100
# Returns GUIDs only, no full entity data loaded

Pagination Best Practices

Use pagination for queries that return large result sets.

Pagination Parameters

GET /report/{reportType}?q=Page={page},PageSize={pageSize}

• Page - Page number (starts at 1)
• PageSize - Results per page

Pagination Detection

The Web SDK uses a PageSize + 1 pattern to indicate more results:

More pages available:

{
  "Rsp": {
    "Status": "TooManyResults",
    "Result": [
      /* PageSize + 1 entities */
    ]
  }
}

Last page:

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      /* PageSize or fewer entities */
    ]
  }
}

Optimal Page Size

Recommended page sizes:

• Small entities (basic properties): 1000-5000
• Medium entities (typical cardholders): 500-1000
• Large entities (with many relationships): 100-500

Factors affecting page size:

• Network bandwidth
• Memory constraints
• Processing time requirements
• Cache warming needs

Pagination with Cache Warming

Combine pagination with DownloadAllRelatedData for optimal bulk processing:

GET /report/CardholderConfiguration?q=Page=1,PageSize=1000,DownloadAllRelatedData=true

Result:

• Returns 1000 cardholder GUIDs (or PageSize + 1 if more exist)
• Loads complete data for all 1000 cardholders into cache
• Subsequent entity queries are served from cache

Endpoints supporting pagination:

• /report/EntityConfiguration
• /report/CardholderConfiguration
• /report/CredentialConfiguration
• /report/UserReport
• /report/UserGroupReport
• /report/AccessRuleConfiguration

Connection Pooling

HTTP Connection Management

Problem: Creating new HTTP connections for each request adds overhead.

Solution: Use HTTP connection pooling in your client. Most HTTP client libraries support connection pooling and keep-alive connections.

Key configuration options:

• Enable keep-alive connections
• Set appropriate pool size (10-20 connections typical)
• Configure retry logic for transient failures
• Set reasonable timeouts

Performance gain: Reduces request overhead by 20-50ms per request.

Query Optimization

Use Specific Filters

Inefficient (retrieves all, filters client-side):

GET /report/CardholderConfiguration?q=Page=1,PageSize=10000
# Client filters for "John" locally

Efficient (filters server-side):

GET /report/CardholderConfiguration?q=FirstName=John,FirstNameSearchMode=Contains,Page=1,PageSize=100

Performance gain: Reduces data transfer by 99% (100 vs 10000 results).

Combine Filters

Filters use AND logic - combine them for precise queries:

GET /report/CardholderConfiguration?q=FirstName=John,FirstNameSearchMode=Contains,AccessStatus@Active,Page=1,PageSize=100

Result: Only active cardholders with "John" in first name.

Summary: Performance Optimization Checklist

Apply these optimizations for maximum performance:

Essential (Apply Always)

• Use Accept: text/json header
• Use field projection (specify only needed properties)
• Implement session keep-alive strategy
• Use batch operations for multiple entities

High-Impact (Apply When Applicable)

• Use pagination for large result sets
• Use DownloadAllRelatedData for bulk operations
• One user account per application
• Use event subscriptions for real-time applications

Optimization by Use Case

Bulk data export:

1. Use DownloadAllRelatedData=true
2. Use large page sizes (1000-5000)
3. Implement session keep-alive
4. Use batch entity queries after cache warming

Real-time monitoring:

1. Subscribe to events (automatic keep-alive)
2. Use field projection for entity queries
3. Cache entity data in your application

Short-lived scripts:

1. Accept session creation overhead
2. Use batch operations
3. Use field projection
4. Use pagination for large queries

Long-running applications:

1. Implement periodic keep-alive (4 minutes)
2. Use event subscriptions for real-time monitoring (provides automatic keep-alive)
3. Cache frequently accessed entity data in your application
4. Monitor session expiration and implement re-authentication

Additional Resources

• Getting Started Guide - Session lifecycle details
• Entity Operations Guide - Batch operation syntax
• Troubleshooting Guide - Performance issue diagnosis
• Postman Collection - Example requests