Guidelines: build an AXIS frontend

Pass user context consistently

The following parameters are the common query parameters that work across most endpoints. Pass them on every request where the endpoint accepts them.

Use:

• lang for localization
• max_rating for the maximum content rating the current user should see
• device for device-specific offer filtering
• sub for active subscription codes

Missing context can cause:

• Wrong-language content
• Content above the user's rating limit
• Incorrect offers for the current device
• Offers that do not match the user's active subscriptions

Use slugs for routes

Use slugs in user-facing app routes.

Example:

/shows/breaking-bad

Most resources can be fetched by ID or slug. Use slugs for URL routing, and use IDs when you already have them from another API response.

Choose expansion carefully

The expand parameter controls how much hierarchy is returned.

Expansion	Use When
expand=all	You need the complete hierarchy, such as show, seasons, and episodes
expand=children	You only need immediate child items
expand=parent	You need immediate parent context
expand=ancestors	You need the full parent hierarchy

expand=all can simplify implementation, but it can also produce large payloads for shows with many seasons and episodes.

For production applications, consider loading hierarchy data incrementally where possible.

Load hierarchy data incrementally where possible

For show, season, and episode navigation, choose the smallest expansion that supports the current screen.

Examples:

• Use expand=all when a content detail page truly needs the full hierarchy.
• Use expand=children when navigating from a show to its immediate seasons or from a season to its episodes.
• Use expand=parent when an episode needs its immediate parent season context.
• Use expand=ancestors when the full parent hierarchy is required.

This helps reduce payload size and response time for navigation experiences.

Handle loading and error states

API-driven screens should handle documented response cases.

Case	Frontend Handling
404 item, list, or page not found	Show a not-found screen; do not retry
400 invalid query parameters	Fix the request, such as invalid max_rating format
500 server error	Show an error state and retry once after a short delay
Network error	Show offline or error state and retry with backoff

For newly published content, see "Retry New Content Carefully" below.

Use paging.next

List and search responses include a paging object.

Always use paging.next directly to load the next page. Do not construct pagination URLs manually.

const response = await fetch(`https://{api-host}${list.paging.next}`);

When paging.next is null, there are no more pages.

Keep public and user-scoped calls separate

User data endpoints require a JWT Bearer token from your authentication provider.

These endpoints are not public. They are scoped to the signed-in user.

Examples include:

• Bookmarks
• Continue watching
• Watched events
• Ratings

Load user data after sign-in.

When loading user state in parallel, handle failed user-data calls gracefully. The source example uses .catch(() => null) for bookmarks, continue watching, and ratings.

Use images that AXIS returns

Items and lists return images as an images dictionary.

Common keys include:

• poster
• hero
• thumbnail
• banner

These URLs already point to axis-svc-shain.

Use returned image URLs directly in <img> tags where possible.

If you need custom image transformations, use Shain transformation options or extract the image ID from the Shain URL and rebuild the transformed URL.

Use responsive images when needed

Use srcset to deliver appropriately sized images to different viewports.

The source guide shows responsive image generation using different widths, such as:

• 320
• 640
• 1280

Use responsive Shain images when your UI needs different image sizes across screen widths.

Use configuration variables set in the Presentation Manager

Define custom configuration variables in the Presentation Manager to allow editors to control front-end behaviors.

Call /config/ once at startup to get the sitemap, navigation, and runtime rules.

Retry new content carefully

Content may not be immediately available after CMS publication.

If your app receives a link to newly published content and receives a 404, retry once or twice with a short delay before showing a not-found screen.

Do not retry indefinitely. After the retry attempts fail, show the not-found state.