Skip to content

feat(content-preview): add metadataApiHost prop for regional metadata routing#4615

Merged
mergify[bot] merged 3 commits into
box:masterfrom
mborkowski-box:feat/metadata-api-host
Jun 9, 2026
Merged

feat(content-preview): add metadataApiHost prop for regional metadata routing#4615
mergify[bot] merged 3 commits into
box:masterfrom
mborkowski-box:feat/metadata-api-host

Conversation

@mborkowski-box

@mborkowski-box mborkowski-box commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a new optional metadataApiHost prop to ContentPreview (forwarded down to ContentSidebar) that lets host applications route metadata instance endpoints to a regional metadata host, while every other API call continues to use apiHost.

Why

Some Box deployments need file/folder metadata to live in a specific region (e.g. https://api-jp.box.com) for data-residency reasons. Today, all metadata calls flow through a single apiHost. A second, optional host is required so that file/folder metadata reads/writes can be pinned to a regional gateway, while shared resources (templates, taxonomies, suggestions, options, queries) stay on the global host.

What changed

  • New optional prop on ContentPreview and ContentSidebar: metadataApiHost?: string. Forwarded into APIOptions.
  • APIOptions.metadataApiHost is stored on Base and a small shared helper buildApiUrl(host) is added so subclasses can derive a /2.0 URL from any host.
  • Metadata adds getMetadataInstanceBaseUrl() and uses it from getMetadataUrl() / getMetadataUrlForFolder(). When metadataApiHost is set and distinct from apiHost, file/folder metadata instance endpoints route through it; otherwise they fall back to apiHost.
  • Templates, template field options, taxonomies, taxonomy nodes, suggestions, and metadata queries are intentionally not affected and continue to use apiHost.

Backward compatibility

The new prop is fully optional and forward-compatible:

  • undefined, empty string, or a value equal to apiHost produce URLs that are byte-identical to today's behavior.
  • Consumers that never set the prop see no change.
  • Dropping the prop after setting it is a no-op.

Unit tests cover all three branches (regional, fallback, and "all non-instance endpoints stay on apiHost").

How to test

The prop only changes URL routing, so the only meaningful end-to-end test is loading Preview/Sidebar against a real regional gateway and confirming metadata-instance traffic goes there while every other endpoint still hits apiHost.

Steps:

  1. Mount ContentPreview (or a downstream consumer that wraps it) with:
    • apiHost = "https://api.box.com"
    • metadataApiHost = "https://api-jp.box.com" (or whichever regional host monoproxy is forwarding to)
  2. Open a file that has metadata, expand the Metadata sidebar, and watch DevTools → Network:
    • Should route through metadataApiHost:
      • GET/POST/PUT/DELETE /2.0/files/{id}/metadata[/{scope}/{template}]
      • GET/POST/PUT/DELETE /2.0/folders/{id}/metadata[/{scope}/{template}]
    • Should stay on apiHost:
      • /2.0/metadata_templates/... (templates, schema, field options)
      • /2.0/metadata_taxonomies/... (taxonomies and nodes)
      • /2.0/metadata_instances/suggestions
      • metadata queries (execute_read)
  3. Reload without metadataApiHost set — every metadata request should go to apiHost, identical to current production behavior.

Summary by CodeRabbit

  • New Features

    • Added support for optional metadata API host configuration, allowing metadata requests to be directed to a different host than the main API endpoint.
  • Documentation

    • Updated ContentPreview and ContentSidebar documentation to include details about the new metadata API host configuration option.
  • Tests

    • Introduced comprehensive test coverage for metadata host configuration, including fallback and edge case scenarios.

mborkowski-box and others added 2 commits June 8, 2026 22:01
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@coderabbitai

coderabbitai Bot commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a964a07f-d081-4f2d-ada7-2b08dbf67944

📥 Commits

Reviewing files that changed from the base of the PR and between aed0f4e and 5a6ffe1.

📒 Files selected for processing (10)
  • src/api/Base.js
  • src/api/Metadata.js
  • src/api/__tests__/Metadata.test.js
  • src/common/types/api.js
  • src/elements/content-preview/ContentPreview.js
  • src/elements/content-preview/__tests__/ContentPreview.test.js
  • src/elements/content-preview/stories/ContentPreview.mdx
  • src/elements/content-sidebar/ContentSidebar.js
  • src/elements/content-sidebar/__tests__/ContentSidebar.test.js
  • src/elements/content-sidebar/stories/ContentSidebar.mdx

Walkthrough

This PR adds optional metadataApiHost configuration to route metadata instance endpoints (file and folder /metadata/... paths) to a regional host while preserving the existing apiHost for templates, taxonomies, and other metadata queries. The feature cascades from the API layer through ContentPreview and ContentSidebar components.

Changes

Regional Metadata Instance Endpoint Routing

Layer / File(s) Summary
API type definition and Base class foundation
src/common/types/api.js, src/api/Base.js
APIOptions gains metadataApiHost?: string type. Base class now accepts, stores, and propagates metadataApiHost through the constructor. New buildApiUrl(host) helper normalizes host URLs with /2.0 suffix.
Metadata instance URL routing implementation
src/api/Metadata.js
getMetadataInstanceBaseUrl() conditionally routes file and folder metadata instance endpoints through metadataApiHost when configured and distinct from apiHost, falling back to getBaseApiUrl() otherwise. getMetadataUrl() and getMetadataUrlForFolder() use this helper for instance paths while preserving existing behavior for scoped and templated queries.
Metadata URL routing test coverage
src/api/__tests__/Metadata.test.js
Extended tests verify metadataApiHost routing for file and folder metadata instances, including fallback behavior when unset or equal to apiHost, trailing slash normalization, and preservation of existing behavior for templates, suggestions, options, and taxonomy endpoints.
ContentPreview component integration
src/elements/content-preview/ContentPreview.js, src/elements/content-preview/__tests__/ContentPreview.test.js, src/elements/content-preview/stories/ContentPreview.mdx
ContentPreview accepts optional metadataApiHost prop, threads it into API constructor options, and forwards it to ContentSidebar. Tests verify prop forwarding; documentation describes scope and transitional behavior.
ContentSidebar component integration
src/elements/content-sidebar/ContentSidebar.js, src/elements/content-sidebar/__tests__/ContentSidebar.test.js, src/elements/content-sidebar/stories/ContentSidebar.mdx
ContentSidebar accepts optional metadataApiHost prop and passes it into API instance configuration to enable regional routing for metadata instance endpoints. Tests verify prop acceptance and forwarding; documentation describes scope and transitional behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

ready-to-merge

Suggested reviewers

  • jmcbgaston
  • jackiejou
  • tjuanitas

Poem

🐰 A regional route for metadata's way,
Instance endpoints have their own path to play,
Templates stay home with the standard host dear,
Props flow right through without any fear,
Sidebar and preview now both dance with glee!

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately describes the main feature added: a metadataApiHost prop enabling regional metadata routing in ContentPreview.
Description check ✅ Passed The description is comprehensive and well-structured, covering summary, rationale, detailed changes, backward compatibility, and testing steps.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 Biome (2.4.16)
src/api/Base.js

File contains syntax errors that prevent linting: Line 21: 'import type' are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 22: 'import type' are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 28: return types can only be used in TypeScript files; Line 33: return types can only be used in TypeScript files; Line 38: return types can only be used in TypeScript files; Line 43: return types can only be used in TypeScript files; Line 60: return types can only be used in TypeScript files; Line 60: expected a semicolon to end the class property, but found none; Line 60: Expected an identifier, a string literal, a number literal, a private field name, or a computed name but instead found '; Line 65: return types can only be used in TypeScript files; Line 70: return types can only be used in TypeScript files; Line 75: return types can only be used in TypeScript files; Line 80: return types can only be

... [truncated 4112 characters] ...

only feature. Convert your file to a TypeScript file or remove the syntax.; Line 383: Type annotations are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 384: Type annotations are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 385: Type annotations are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 386: Type annotations are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 387: return type annotation are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 396: type annotation are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.

src/api/Metadata.js

File contains syntax errors that prevent linting: Line 7: 'import type' are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 55: 'import type' are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 56: 'import type' are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 66: 'import type' are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 67: 'import type' are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 76: Type annotations are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 76: return type annotation are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 86: Type annotations are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 86:

... [truncated 24149 characters] ...

y feature. Convert your file to a TypeScript file or remove the syntax.; Line 1600: Type annotations are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 1601: Type annotations are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 1602: Type annotations are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 1603: Type annotations are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 1604: optional parameters are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 1604: Type annotations are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.

src/common/types/api.js

File contains syntax errors that prevent linting: Line 4: 'import type' are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 5: 'import type' are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 6: 'import type' are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 8: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 16: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 26: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 28: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 35: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 37: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 45: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 55: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 57: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 65: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 69: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 71: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 76: type alias are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.; Line 113: 'export type' declarations are a TypeScript only feature. Convert your file to a TypeScript file or remove the syntax.

  • 3 others
🔧 ast-grep (0.43.0)
src/api/__tests__/Metadata.test.js

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@mborkowski-box mborkowski-box changed the title Feat/metadata api host feat(content-preview): add metadataApiHost prop for regional metadata routing Jun 9, 2026
@mborkowski-box mborkowski-box marked this pull request as ready for review June 9, 2026 09:50
@mborkowski-box mborkowski-box requested review from a team as code owners June 9, 2026 09:50

@alexkirillovtech alexkirillovtech left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@tjuanitas tjuanitas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@mergify

mergify Bot commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

Merge Queue Status

  • Entered queue2026-06-09 15:46 UTC · Rule: Automatic strict merge
  • Checks passed · in-place
  • Merged2026-06-09 16:00 UTC · at bb36ba6cfeb3043d07a78c4b1689f8a47feff89b · squash

This pull request spent 13 minutes 47 seconds in the queue, including 13 minutes 26 seconds running CI.

Required conditions to merge

@mergify mergify Bot merged commit d6a70d7 into box:master Jun 9, 2026
9 of 10 checks passed
@mergify mergify Bot removed the queued label Jun 9, 2026
@mborkowski-box mborkowski-box deleted the feat/metadata-api-host branch June 9, 2026 16:41
@mborkowski-box mborkowski-box restored the feat/metadata-api-host branch June 9, 2026 16:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants