Technical reference

db-http provides a shared framework, com.brightspot.dbhttp.HttpDatabase, that each service-specific module builds on to expose an external HTTP API as a Brightspot federated search source. This page documents the shared framework; see the page for each service for its specific classes, fields, and configuration.

Dependencies

HttpDatabase depends on Dari's AbstractDatabase and query/predicate APIs (com.psddev.dari.db), which ship with the Brightspot CMS runtime. Individual service modules add their own dependencies (an SDK or HTTP client for the external service) — see each service's page for its specific requirements.

Installation

Maven

<!-- Requires Brightspot 5.0 or later. -->
<dependency>
    <groupId>com.brightspot.dbhttp</groupId>
    <artifactId>db-http</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

// Requires Brightspot 5.0 or later.
implementation 'com.brightspot.dbhttp:db-http:1.0.0'

Gradle (Kotlin DSL)

// Requires Brightspot 5.0 or later.
implementation("com.brightspot.dbhttp:db-http:1.0.0")

Install this dependency once; each service module (for example adobe or getty) additionally depends on it.

API reference

HttpDatabase

An abstract AbstractDatabase<Void> that dispatches a query to either a keyword search or an ID-based lookup against an external service.

Method	Parameters	Returns	Description
search	Query<T> query, long offset, int limit	PaginatedResult<T>	Abstract. Searches the external service using the query's search predicates.
getByExternalIds	Query<T> query, long offset, int limit, List<ExternalId> externalIds	PaginatedResult<T>	Abstract. Fetches items from the external service by their resolved ExternalId records.
buildAndPopulate	String externalId, Class<E> itemClass, Query<T> query, Consumer<E> populator	T	Resolves an external Id to a Brightspot object (creating the ExternalId mapping if one does not exist), applies populator to fill in fields from the external service, and returns the populated object.
buildAndPopulate	String externalId, Class<E> itemClass, Query<T> query, Consumer<Query<ExternalId>> queryCustomizer, Consumer<ExternalId> mappingCustomizer, Consumer<E> populator	T	Overload for implementations that add Modification-based fields to ExternalId for additional scoping, such as per-account isolation. queryCustomizer adds conditions to the mapping lookup query, and mappingCustomizer initializes those fields on a newly created mapping. Used by every multi-account module.
buildAndPopulate	ExternalId externalId, Class<E> itemClass, Query<T> query, Consumer<E> populator	T	Overload used from getByExternalIds, where the ExternalId mapping is already resolved.
readCount	Query<?> query	long	Short-circuits ID-based count queries to the number of Ids requested, avoiding a per-item API call to the external service.

Subclasses implement search and getByExternalIds; readPartial (inherited dispatch logic) inspects the query's predicate and routes to one or the other.

ExternalId

A Record that persists the mapping between an external service's identifier and a Brightspot UUID.

Field	Type	Description
source	String	The fully qualified class name of the HttpDatabase implementation that owns this mapping, scoping it so identical external Ids from different services don't collide.
externalId	String	The external service's identifier for the item.
brightspotId	UUID	The Brightspot record Id created for this external item.

Implementations that need additional scoping — for example per-account isolation when a service supports multiple linked accounts — add indexed fields to ExternalId through Dari's Modification system rather than subclassing it directly.

Configuration

Every service module follows the same configuration convention:

• Credentials are stored on a small Record (commonly named <Service>ApiClient or embedded directly in a settings Modification), with secret fields marked @ToolUi.Secret so they're hidden in the CMS Tool UI after being saved.
• That credentials record is exposed through a Modification<SiteSettings> (per-site configuration) or a Modification<CmsTool> (global configuration), grouped under the Integrations tab and a cluster named for the service.
• A SourceDatabaseProvider implementation reads the resolved settings — per site, or from the global CmsTool singleton — and constructs the HttpDatabase instance used to serve searches for that service.
• Services that import content on behalf of an individual editor (rather than a shared service account) additionally store a per-user OAuth-linked account record, and a SearchExtension adds an account picker and "link another account" affordance to the search UI.

See each service's page under this section for its exact settings classes and field names.