Getting started: build a bespoke backend service
Overview
A bespoke backend service is an integration layer that sits between AXIS Frontend APIs and your downstream clients.
Use a bespoke service when your project needs to:
- Aggregate multiple AXIS API calls into one client response
- Transform AXIS responses into an existing client contract
- Enrich AXIS content with data from your own systems
- Apply custom business rules, such as geo restrictions or entitlement filtering
- Expose AXIS data in another format, such as GraphQL, RSS, XMLTV, or a custom REST API
- Add application-level caching, resilience, and monitoring
Do not build a bespoke service only to proxy AXIS Frontend APIs without adding value.
Before you start
Before you design or build the service, confirm:
- Which downstream clients will consume the service
- Which AXIS Frontend APIs your service needs
- Which request context values affect responses, such as language, rating limit, device, and subscription
- Whether your service needs user-specific data, partner-owned data, or project-specific policy enforcement
- Development, staging, and production hostnames with the platform team
- Authentication requirements for user-specific AXIS endpoints, partner systems, or internal services
Systems involved
| System | Purpose |
|---|---|
| AXIS Frontend APIs | Catalog, display, linear, search, and UX metadata APIs. |
| Bespoke backend service | Your service that aggregates, transforms, enriches, filters, caches, or converts AXIS data. |
| Downstream clients | Apps, devices, partner systems, or third-party services. |
| Optional partner systems | Ratings, recommendations, entitlements, analytics, user preferences, or geo services. |
AXIS Frontend APIs
| Service | Purpose |
|---|---|
axis-api-catalog | Content metadata, items, and lists. |
axis-api-display | Pages, navigation, and layout configuration. |
axis-api-linear | Live and scheduled programming. |
axis-api-search | Content discovery and full-text search. |
axis-api-uxmeta | User-specific metadata such as bookmarks and watch history. |
Don't extend the search feature on top of axis-api-search. May you need a bespoke search engine, contact the AXIS team to design and implement a new search feature.
The actual host names are environment-specific. Confirm development, staging, and production hosts with the platform team.
Authentication
AXIS Frontend APIs are for use in frontends and integrations. They do not need an API key for read-only requests. Tenant routing is handled by the CDN, so requests do not include a tenant ID in the URL. If your service calls user-specific AXIS endpoints, user-specific partner systems, or partner-owned services, handle those authentication requirements separately.
Essential query parameters
Pass the relevant user and request context on outbound AXIS calls. The source guide identifies these as essential query parameters, and they should be included on every outbound request where the endpoint accepts them.
| Parameter | Purpose |
|---|---|
lang | Returns content in the user's preferred language. |
max_rating | Filters content above the user's rating limit. |
device | Filters offers based on the target device. |
sub | Filters offers based on active subscription codes. |
For user-specific or offer-bearing responses, include all parameters that affect visibility, offer filtering, or eligibility. If a parameter changes the AXIS response, include it in your cache key as well.
Example: Aggregate a content detail experience
A bespoke service often aggregates multiple AXIS responses into a single client response. For example, a project may combine item metadata with live schedule information when building a content detail experience. Instead of requiring the client to make multiple requests, the backend service can retrieve AXIS data in parallel and return a single response.
GET /v0.1/items/{showId}?expand=all&lang={lang}&max_rating={rating}&device={device}&sub={sub}
GET /v0.1/schedules/live?lang={lang}
The bespoke service then combines the responses into a client-specific contract.
Typical implementation flow
- Receive a request from the client.
- Validate client parameters and user context.
- Build outbound AXIS requests.
- Execute independent AXIS calls in parallel where possible.
- Transform or enrich responses if required.
- Apply project-specific business rules where required.
- Return a client-specific response.
Many implementations also add caching, monitoring, resiliency, and other features that are appropriate for their architecture.