Canonical Naming

Canonical naming is a unique, non-versioned naming system used to assign specific API endpoints at Indee. This system simplifies API management and enhances flexibility by allowing clients to avoid hardcoding version numbers in their API requests. The advantages of using canonical names include:

• Seamless Upgrades: Upgrade a single API for a specific app, product, or customer without requiring any changes to client-side code.
• Concurrent Version Support: Support multiple versions of your app concurrently, eliminating API confusion and ensuring smooth transitions between versions.
• Selective Endpoint Management: Sunset specific customers or endpoints without affecting other customers, providing targeted updates and maintaining overall system stability.

By adopting canonical naming, you can simplify your API management process, enhance flexibility, and improve the overall robustness of your applications.

Example of Canonical Naming

For the Watch API Login and Projects API endpoints, the canonical naming representation is as shown below:

{
  "watch.auth.session.login": "https://api.indee.tv/v2/watch/auth/login",
  "watch.content.project.list": "https://api.indee.tv/v2/watch/content/projects"
}

Canonical Naming Format

Canonical names include a namespace to prevent internal conflicts, formatted as:

product.category.feature.action

• product: Indee products and the associated APIs. These include watch, admin, guild, etc.
• category: The broad category where the endpoint falls, like auth, content, stream etc.
• feature: Indicates the product feature such as project, genre, brand, video, and screener.
• action: A verb indicating the action you want to perform for the feature such as login, list, etc.

Clients will refer to API endpoints using these canonical names, avoiding the need to hardcode URLs.

Retrieving Canonical Endpoints: The Meta API

Clients need a way to get the list of canonical endpoints and their corresponding actual URLs. This is where the Meta API comes in.

Meta API

The Meta API, the "API of APIs," provides a list of canonical endpoints and their actual URL mappings. It is a simple endpoint:

GET v2/watch/meta/endpoint-set

This endpoint is the only one client's hardcode. It is the first API called by any Indee client to obtain the actual endpoints needed.

How the Meta API Works

Here's how the Meta API operates to provide clients with the necessary endpoint mappings:

1. Client Registration: When a client application is registered on the server, a unique API key is issued.
2. Meta API Call: The client initiates a call to the Meta API, presenting the API key.
3. Response: The server responds with a map of canonical names and the corresponding endpoints, based on the provided API key.

This process ensures clients have the latest endpoint mappings, enabling seamless updates and reducing the need for client-side changes.