Concepts and guidelines: build a bespoke backend service

Bespoke backend service

A bespoke backend service is middleware built by your team on top of AXIS Frontend APIs.

It acts as an integration layer between AXIS and your downstream consumers, such as web applications, mobile apps, connected TV applications, partner systems, or third-party services.

A bespoke backend service can:

• Aggregate data from multiple AXIS APIs
• Transform AXIS responses into a client-specific contract
• Enrich AXIS data with information from external systems
• Apply project-specific business rules
• Expose AXIS data through a different API or format

A bespoke backend service should provide clear integration value rather than simply proxying AXIS APIs.

AXIS Frontend APIs

AXIS Frontend APIs expose read-only platform data that can be consumed directly by frontend applications or used as the foundation for bespoke backend services.

Common AXIS Frontend APIs include:

Service	Purpose
axis-api-catalog	Content items, metadata, and lists
axis-api-display	Pages, layouts, and navigation configuration
axis-api-linear	Live and scheduled programming
axis-api-search	Full-text content discovery
axis-api-uxmeta	User-specific metadata such as bookmarks, continue watching, ratings, and watch history

Most AXIS Frontend APIs are publicly consumable read-only APIs.

User-specific APIs and metadata may require user context or a JWT, depending on the endpoint.

Use the appropriate AXIS service for each data need.

Obtain the actual hostnames for each environment from the platform team. Staging and production use different hosts.

Run independent API calls in parallel

When aggregating data from multiple AXIS endpoints, execute independent calls in parallel.

Do not make sequential calls unless one response is required to build the next request.

Example: a content detail response may fetch item hierarchy and live schedule data in parallel, then merge the results before returning a single client response.

Parallel fan-out keeps total latency closer to the slowest individual dependency instead of the sum of all dependencies.

Aggregation

Aggregation combines data from multiple AXIS API responses into a single client response.

This is one of the most common bespoke service patterns.

Example use cases include:

• Content details experiences that combine item metadata, seasons, episodes, and live schedule information
• Home pages that combine multiple curated content lists
• Unified responses that combine catalog, schedule, and search data

Transformation

Transformation reshapes AXIS responses into the format expected by your consumers.

Use transformation when:

• An existing application expects different field names
• Your front end requires a smaller or flatter payload
• Multiple AXIS fields need to be normalized into a client-specific model
• You need to maintain compatibility with an existing API contract

Transformation adapts the AXIS data model without changing the underlying content.

Keep transformation logic explicit

Use transformation when your downstream clients need a response shape different from the AXIS response.

Transformation can include:

• Renaming fields
• Changing nesting or structure
• Normalizing types
• Reducing payload size
• Adapting AXIS responses to a legacy contract

Keep transformers stateless and thin where possible. If transformation logic grows complex, separate it from basic HTTP proxying.

Enrichment

Enrichment combines AXIS data with information from external systems.

Examples include:

• External ratings
• Recommendation services
• User preferences
• Entitlement systems
• Analytics-derived popularity data
• Partner-owned metadata

An enrichment service retrieves AXIS content and combines it with data from additional sources before returning the response.

Some projects treat enrichment as optional data, while others require it as part of the response contract.

Design enrichment to degrade gracefully

Make enrichment failures non-fatal where possible. If an enrichment source is unavailable, return the AXIS data without enrichment rather than failing the entire response.

Format conversion

A bespoke backend service can expose AXIS data through a different protocol or format.

Examples include:

• GraphQL APIs built on top of AXIS REST APIs
• RSS or Atom feeds
• XMLTV feeds for EPG consumers
• Custom REST APIs for partner systems

Format conversion is useful when a downstream consumer cannot consume AXIS REST responses directly.

Query context

AXIS responses can vary depending on the request context.

Common AXIS query parameters include:

Parameter	Purpose
lang	Returns localized content
max_rating	Applies parental-rating filtering
device	Filters offers for the target device
sub	Filters offers for active subscription codes

If a context value changes the response, it should also be considered when designing cache keys.

Projects may also apply additional business rules such as entitlement checks, segmentation logic, or geo restrictions within their bespoke service.

Forward required query parameters

If a parameter affects the AXIS response, include it in both the outbound request and your cache key.

Be careful with custom filtering

If AXIS does not handle a business rule natively, your bespoke service may apply custom filtering after fetching AXIS data.

Examples include:

• Geo-restrictions
• Custom entitlements
• Customer-specific availability rules

Be mindful of pagination. Filtering after fetching may return fewer items than the requested page size. Either fetch a larger page or document the behavior for clients.

Use AXIS pagination safely

AXIS paginated responses include a paging.next path.

Do not reconstruct pagination URLs manually. Use the next path returned by the API, or convert it into your own pagination token scheme.

This preserves server-provided paging state and avoids accidentally dropping filters or query parameters.

Caching

AXIS Frontend APIs are typically delivered through a CDN.

Eventual consistency

AXIS Frontend APIs read from asynchronously updated projections.

After content is published, it may not be visible immediately through the Frontend APIs.

Because projections are updated asynchronously, newly published content may not be immediately available through front end API responses.

The delay is typically measured in seconds, although it can occasionally be longer during periods of high-activity.

When designing a bespoke service, remember that both may affect content visibility:

• Projection propagation delay
• Application cache TTL

Together, these factors determine how quickly newly published content becomes visible to end users.

Error mapping

AXIS APIs return a consistent error structure when a request fails.

Example:

{
  "code": "ITEM_NOT_FOUND",
  "message": "The item with id 'abc123' was not found.",
  "details": {}
}

A bespoke backend service should map AXIS errors into its own client-facing error contract.

Do not leak internal AXIS error messages directly to clients. Keep platform-specific details in logs and return client-appropriate messages from your service.

The chosen mapping approach should remain consistent across all endpoints.

Graceful degradation

A bespoke backend service should avoid failing an entire response when only part of the response is unavailable.

Common degradation strategies include:

• Serving cached data
• Returning partial responses
• Omitting optional enrichment
• Returning null for unavailable sections
• Isolating repeatedly failing downstream dependencies

For aggregated responses, degradation behavior should be defined explicitly so clients can handle incomplete data correctly.

Set Explicit Timeouts

Set timeouts on outbound calls to AXIS Frontend APIs.

Reasonable timeouts are:

Call type	Timeout
Single item or list	3-5 seconds
Batch list call	5-8 seconds
Search	5-8 seconds
Overall aggregated request	10-15 seconds

Use parallel fan-out so the total time is based on the slowest dependency, not the sum of all dependencies.

Protect the service with resilience policies

Use resilience patterns where appropriate:

• Retries for transient failures
• Circuit breakers for repeated downstream failures
• Stale cache fallback
• Partial response fallback
• Request timeouts

Circuit breaking protects your service from repeatedly calling failing dependencies.

Security and policy enforcement

A bespoke backend service is often responsible for applying project-specific policies before returning data to consumers.

Examples include:

• Entitlement enforcement
• Geo-restrictions
• Content visibility rules
• User-specific response shaping

When custom policies affect the returned data, the behavior should be documented clearly so downstream consumers understand how results are filtered or modified.

Monitor before go-live

Before production rollout, confirm:

• Parallel fan-out is implemented for aggregated calls
• All outbound HTTP clients have timeouts
• Retry or circuit-breaker policies are configured
• Graceful degradation is implemented
• Required query parameters are forwarded
• Cache keys include all response-changing parameters
• TTLs match content freshness requirements
• Post-publish retry behavior is implemented where needed
• AXIS API errors are logged with enough context for debugging
• Outbound call latency and error rates are monitored
• Alert thresholds are configured for elevated AXIS API errors

Use parallel fan-out so the total time is based on the slowest dependency, not the sum of all dependencies.