Configure Region Endpoints in Ruby Utils SDK

Contentstack services are available across multiple regions with different endpoint URLs. Hardcoding these URLs requires code changes as regions and services evolve. The Ruby Utils SDK resolves the correct endpoint dynamically from the canonical regions registry, allowing the same initialization code to work across supported regions without hardcoded strings.

Use region resolution when your application supports multiple regions or cloud-specific regions.

This feature is optional if:

• You connect to only one Contentstack region
• You hardcode the endpoint

The following table maps each use case to its section and primary API call.

Mandatory:

• contentstack_utils gem installed, version 1.3.0 or later (the version that introduced ContentstackUtils::Endpoint.get_contentstack_endpoint). See Ruby Utils SDK Setup Guide.

Optional:

• Familiarity with Contentstack regions: Selecting a Region in SDKs

On the first call, the SDK loads regions.json from disk or downloads it from the content delivery network (CDN) if the file is absent, then caches the parsed registry in memory. Subsequent calls resolve endpoints from the in-memory cache without additional disk or network I/O.

Note: The cache has no TTL or timer. Registry changes on the CDN require a process restart, or you call ContentstackUtils::Endpoint.refresh_regions manually. See Refresh the Registry Manually.

require 'contentstack_utils'

begin
  url = ContentstackUtils::Endpoint.get_contentstack_endpoint(
    region:  '<CONTENTSTACK_REGION>',
    service: '<SERVICE_KEY>'
  )
  # => "https://cdn.contentstack.io"
rescue ArgumentError => e
  puts "Invalid region or service: #{e.message}"
rescue RuntimeError => e
  puts "Registry error: #{e.message}"
end

Use this method when you need more than one service endpoint for the same region.

When service is omitted, nil, or blank, the method returns a hash of all service endpoints for the region. This is expected behavior, not an error.

begin
  endpoints = ContentstackUtils::Endpoint.get_contentstack_endpoint(region: '<CONTENTSTACK_REGION>')
  # => {
  #      "application"       => "https://eu-app.contentstack.com",
  #      "contentDelivery"   => "https://eu-cdn.contentstack.com",
  #      "contentManagement" => "https://eu-api.contentstack.com",
  #      ...
  #    }
rescue ArgumentError => e
  puts "Invalid region: #{e.message}"
rescue RuntimeError => e
  puts "Registry error: #{e.message}"
end

Most applications should use the default overload, which returns a full HTTPS URL. Use omit_https: true only when an API specifically expects a hostname without the scheme, since the SDK's host configuration adds https:// internally and a full URL would double the scheme. The connection is always HTTPS.

begin
  host = ContentstackUtils::Endpoint.get_contentstack_endpoint(
    region:     '<CONTENTSTACK_REGION>',
    service:    '<SERVICE_KEY>',
    omit_https: true
  )
  # => "cdn.contentstack.io"
rescue ArgumentError => e
  puts "Invalid region or service: #{e.message}"
rescue RuntimeError => e
  puts "Registry error: #{e.message}"
end

The SDK normalizes aliases to the canonical region ID, ignoring case and treating dashes and underscores as equivalent. For the full alias list, see Supported Regions.

begin
  url = ContentstackUtils::Endpoint.get_contentstack_endpoint(
    region:  'azure_na',
    service: 'contentManagement'
  )
  # => "https://azure-na-api.contentstack.com"
rescue ArgumentError => e
  puts "Invalid region or service: #{e.message}"
rescue RuntimeError => e
  puts "Registry error: #{e.message}"
end

region = ENV.fetch('CONTENTSTACK_REGION', 'na')

begin
  url = ContentstackUtils::Endpoint.get_contentstack_endpoint(
    region:  region,
    service: '<SERVICE_KEY>'
  )
rescue ArgumentError => e
  puts "Invalid region or service: #{e.message}"
rescue RuntimeError => e
  puts "Registry error: #{e.message}"
end

ContentstackUtils exposes a top-level proxy that delegates to ContentstackUtils::Endpoint.get_contentstack_endpoint. Use this form when you prefer the shorter module-level call.

begin
  url = ContentstackUtils.get_contentstack_endpoint(
    region:  '<CONTENTSTACK_REGION>',
    service: '<SERVICE_KEY>'
  )
rescue ArgumentError => e
  puts "Invalid region or service: #{e.message}"
rescue RuntimeError => e
  puts "Registry error: #{e.message}"
end

Call ContentstackUtils::Endpoint.refresh_regions whenever the cached registry is outdated, for example after Contentstack publishes a new region or service. ContentstackUtils::Endpoint caches the registry in memory for the lifetime of the process, so a newly published region or service does not resolve until you make this call.

begin
  ContentstackUtils::Endpoint.refresh_regions
rescue RuntimeError => e
  puts "Registry refresh failed: #{e.message}"
end

This downloads the latest regions.json from the Regions Registry, replaces the local copy, and clears the in-memory cache.

Resolves a Contentstack service URL for a given region.

ContentstackUtils::Endpoint.get_contentstack_endpoint(
  region:     'us',
  service:    '',
  omit_https: false
)

All alias lookups are case-insensitive. US, us, and Us all resolve to the na region.

Only dash (-) and underscore (_) are recognized as separators. A region string using any other separator (a space, a dot, or a slash, for example "aws na") does not match any known region or alias and raises the "Invalid region" error above. Dash and underscore variants resolve identically only because both forms are listed as separate alias entries in the regions registry, not because the SDK normalizes separators at runtime.

The Regions Registry is the authoritative list of region identifiers and aliases.

The Regions Registry is the canonical source for all service keys. assetManagement is available for NA only.

This SDK does not expose these values as constants or a module of frozen values, so copy them exactly.

Symptom

begin
  ContentstackUtils::Endpoint.get_contentstack_endpoint(
    region:  'invalid-region',
    service: 'contentDelivery'
  )
rescue ArgumentError => e
  puts e.message  # => "Invalid region: invalid-region"
end

Root cause: The string does not match any region ID or alias in the registry. This is typically caused by a typo or an unsupported region name.

Resolution: Check the Supported Regions table for valid identifiers and aliases.

Symptom

ArgumentError: Service "unknownService" not found for region "eu"

Root cause: The service key does not exist for the resolved region. Some keys (such as assetManagement) are available for NA only.

Resolution: Verify the service key against Supported Services. For non-NA regions, check region-specific constraints noted in that section.

Symptom

begin
  ContentstackUtils::Endpoint.get_contentstack_endpoint(region: 'eu')
rescue RuntimeError => e
  puts e.message  # => "Failed to fetch region metadata: ..."
end

Root cause: The local regions.json file was absent and the network download from the Contentstack registry failed.

Resolution: Run ContentstackUtils::Endpoint.refresh_regions after restoring network connectivity to artifacts.contentstack.com.

Symptom

begin
  ContentstackUtils::Endpoint.get_contentstack_endpoint(region: 'newly-published-region')
rescue ArgumentError => e
  puts e.message  # => "Invalid region: newly-published-region"
end

Root cause: ContentstackUtils::Endpoint caches the regions registry in memory for the lifetime of the process. A region or service that Contentstack published after your process started is not visible until you refresh the cache.

Resolution: Call ContentstackUtils::Endpoint.refresh_regions to reload the registry. See Refresh the Registry Manually.

This section covers caching internals and the resolution flow. Skip it unless you're debugging a caching issue or automating registry refresh in a deployment pipeline. To force a refresh, see Refresh the Registry Manually.

Resolution Flow

get_contentstack_endpoint(region, service, omit_https)
        │
        ▼
  Validate region (raise ArgumentError if blank)
        │
        ▼
  load_regions()
  ┌─────┴──────────────────────────────────────┐
  │  In-memory cache present?  ──Yes──► return  │
  │          │ No                               │
  │          ▼                                  │
  │  regions.json on disk?  ──No──► download    │
  │          │ Yes                              │
  │          ▼                                  │
  │  Parse JSON ──► cache ──► return            │
  └─────────────────────────────────────────────┘
        │
        ▼
  Find region by id or alias (case-insensitive)
        │
        ├── Not found ──► raise ArgumentError
        │
        ▼
  service empty?
        ├── Yes ──► return endpoints hash (optionally strip https)
        │
        └── No  ──► look up service key
                        ├── Not found ──► raise ArgumentError
                        └── Found ──► return URL (optionally strip https)

The in-memory cache is an unsynchronized memoized instance variable. No Mutex or Monitor guards it.

• Risk: Under a threaded application server (such as Puma running with multiple threads), concurrent first calls could race and download the registry more than once.
• Impact: Not data corruption (the downloaded JSON is idempotent), but the first-call cost can be paid more than once under concurrent load.

The registry download has these network characteristics:

• Timeout: Explicit 30-second connect and read timeout.
• Proxy support: Uses http_proxy/https_proxy environment variables automatically if set.
• Firewall: Allow outbound access to artifacts.contentstack.com.