# Understanding the Channel-Endpoint-Model-Category Hierarchy in Bella OpenAPI Routing

> Discover the Channel-Endpoint-Model-Category hierarchy for intelligent routing in Bella OpenAPI. Learn how this structure optimizes AI requests and provider selection for effective load balancing.

- Repository: [Ke Technologies/bella-openapi](https://github.com/lianjiatech/bella-openapi)
- Tags: deep-dive
- Published: 2026-03-06

---

**The Channel-Endpoint-Model-Category hierarchy is a four-level routing structure in Bella OpenAPI that maps AI requests to concrete provider channels through either model-based or endpoint-based resolution paths, enabling intelligent load balancing and provider selection.**

The Bella OpenAPI project (lianjiatech/bella-openapi) implements a sophisticated routing system to direct AI model requests to appropriate provider channels. This system relies on a four-level hierarchy—**Category**, **Endpoint**, **Model**, and **Channel**—that decouples business logic from infrastructure concerns while enabling granular traffic management and failover capabilities.

## The Four Levels of the Hierarchy

The hierarchy is **not a strict parent-child chain**. Instead, it provides flexible linkage patterns where an endpoint can be served either by a model-based channel or by a channel bound directly to the endpoint.

- **Category**: Business-level grouping stored in `CategoryDB` and represented by `EndpointCategoryTree` in `api/sdk/src/main/java/com/ke/bella/openapi/metadata/`. Categories organize endpoints into navigable trees but do not participate in runtime routing decisions.

- **Endpoint**: Capability points such as `/v1/chat/completions` defined in `EndpointDB`. Endpoints link downward to Models (via `model-endpoint` relations) and directly to Channels (via `endpoint-channel` relations).

- **Model**: AI model definitions (e.g., `gpt-4`) stored in `ModelDB`. Models map to terminal models via `linkedTo` fields and connect to Channels through `model-channel` relations.

- **Channel**: Concrete provider instances (e.g., OpenAI GPT-4 channel) stored in `ChannelDB`. Channels hold routing attributes including `priority`, `visibility`, `dataDestination`, and `protocol` that determine selection eligibility.

## How the Hierarchy Powers Request Routing

### The ChannelRouter Decision Flow

In [`api/server/src/main/java/com/ke/bella/openapi/protocol/ChannelRouter.java`](https://github.com/lianjiatech/bella-openapi/blob/main/api/server/src/main/java/com/ke/bella/openapi/protocol/ChannelRouter.java), the `route()` method (lines 46-81) implements the core selection algorithm that traverses the hierarchy:

1. **Entity Resolution**: If a model parameter is provided, the router resolves the terminal model name (following `linkedTo` chains). Otherwise, it targets the endpoint directly.

2. **Channel Retrieval**: The router calls `ChannelService.listActives()` (lines 77-82 in [`api/server/src/main/java/com/ke/bella/openapi/service/ChannelService.java`](https://github.com/lianjiatech/bella-openapi/blob/main/api/server/src/main/java/com/ke/bella/openapi/service/ChannelService.java)) to fetch active channels for either the model (`EntityConstants.MODEL`) or the endpoint (`EntityConstants.ENDPOINT`).

3. **Filtering**: Channels are filtered by safety level, visibility, rate limits, and availability via the `filter()` method.

4. **Priority Selection**: The `pickMaxPriority()` method isolates the highest-priority channels, with `random()` selecting one when multiple channels share the same priority level.

### Model vs. Endpoint Resolution Paths

The hierarchy supports dual resolution strategies:

- **Model-based routing**: When a request specifies a model (e.g., `gpt-4`), `ModelService.fetchTerminalModelName()` resolves any model aliases (as implemented in [`api/server/src/main/java/com/ke/bella/openapi/service/ModelService.java`](https://github.com/lianjiatech/bella-openapi/blob/main/api/server/src/main/java/com/ke/bella/openapi/service/ModelService.java)), then selects channels bound to that terminal model.

- **Endpoint-based routing**: When no model is specified, the router selects channels bound directly to the requested endpoint via the `endpoint-channel` relation.

This flexibility allows Bella OpenAPI to support both model-agnostic endpoints and specific model requirements through the same unified interface.

## Category Management and Endpoint Organization

While Categories do not influence runtime routing, they provide essential business logic grouping. The `CategoryService.listTree()` method (lines 48-60 in [`api/server/src/main/java/com/ke/bella/openapi/service/CategoryService.java`](https://github.com/lianjiatech/bella-openapi/blob/main/api/server/src/main/java/com/ke/bella/openapi/service/CategoryService.java)) builds the category-endpoint tree for UI navigation and permission management. The `EndpointCategoryTree` DTO presents this hierarchy to management interfaces, enabling administrators to organize capability points logically without affecting the routing engine.

## Practical Implementation Example

Below is a minimal snippet demonstrating client-side channel resolution using the Bella OpenAPI hierarchy:

```java
// Assume we have an authenticated ApikeyInfo object (from security layer)
String endpoint = "/v1/chat/completions";
String model    = "gpt-4";               // optional; may be null

ChannelRouter router = BellaContext.getBean(ChannelRouter.class);
ChannelDB channel = router.route(endpoint, model, apikeyInfo, false);

// The returned ChannelDB contains everything needed to invoke the provider
System.out.println("Selected channel: " + channel.getChannelCode());
System.out.println("Protocol: " + channel.getProtocol());
System.out.println("PriceInfo: " + channel.getPriceInfo());

```

If the caller only knows the endpoint, the router automatically falls back to endpoint-bound channels. When a model is specified, the router resolves the terminal model via `ModelService.fetchTerminalModelName()`, then selects the best model-bound channel according to the hierarchy rules.

## Summary

- The **Channel-Endpoint-Model-Category hierarchy** provides a four-level abstraction for routing AI requests in Bella OpenAPI, separating business organization from infrastructure concerns.
- **Categories** organize endpoints for UI management but do not participate in runtime routing decisions.
- **Routing** occurs through either model-based resolution (via `linkedTo` terminal models) or direct endpoint-channel binding, implemented in [`ChannelRouter.java`](https://github.com/lianjiatech/bella-openapi/blob/main/ChannelRouter.java).
- The **`ChannelRouter.route()`** method (lines 46-81) implements the selection logic, filtering by safety, visibility, and priority before randomly selecting among equal candidates.
- **Concrete provider channels** (`ChannelDB`) encapsulate protocol details, pricing, and routing attributes required for request fulfillment.

## Frequently Asked Questions

### What is the difference between model-based and endpoint-based routing?

Model-based routing resolves the terminal model name (following `linkedTo` chains) and selects channels bound to that specific model via `model-channel` relations. Endpoint-based routing selects channels bound directly to the requested capability point via `endpoint-channel` relations. The `ChannelRouter` automatically chooses the appropriate path based on whether the request includes a model parameter.

### How does the Category level influence request routing?

The Category level does not participate in runtime routing decisions. According to the source code in [`CategoryService.java`](https://github.com/lianjiatech/bella-openapi/blob/main/CategoryService.java), categories exist solely for business-level grouping and UI tree construction (`listTree()` method, lines 48-60). They provide logical organization for endpoint management and permission checks but are never referenced by `ChannelRouter` during channel selection.

### What happens when multiple channels have the same priority?

When multiple channels share the highest priority value after filtering, the `pickMaxPriority()` method returns all candidates with that priority level. The `ChannelRouter` then applies `random()` selection among these tied channels to distribute load evenly. This implementation ensures high availability while respecting priority tiers defined in `ChannelDB.priority` fields.

### How is the terminal model resolved in the hierarchy?

Terminal model resolution occurs in `ModelService` when the router encounters a model alias. The system follows the `linkedTo` field chain in `ModelDB` records until reaching a model with no further linkage. This terminal model name becomes the entity code used for `ChannelService.listActives(EntityConstants.MODEL, terminal)` lookups, ensuring requests route to channels capable of serving the concrete model implementation.