Core concepts

Before you start developing and exposing APIs, understand the core objects in the platform. Together they determine "who can see what, where APIs run, and how callers obtain permissions".

Object relationships

Project

The project is the highest-level unit of business and data isolation. APIs, data sources, groups, environments, rules, subscriptions and AI sessions are all isolated by project.

• After logging in you must select or create a project; subsequent requests automatically carry X-Project-Id from the frontend.
• A project has a unique API prefix, used to build open API addresses; case and leading/trailing slashes are ignored when comparing.
• Project members are divided into administrators and members; administrators can maintain members and delete resources within the project.
• Accessing data sources across projects requires "data source authorization"; the authorized party can only use the data and cannot view the connection account and password.

See Project space for details.

Users, roles and menus

The platform uses a "user - role - menu" RBAC model:

• Menu permissions: determine which navigation items and pages are visible after login, as well as the API path rules a role can access.
• Data permissions: on top of menu permissions, users can only see data they created, plus groups and data sources that have been authorized for collaboration.
• Super administrator: has all menus by default and is not limited by role menus; sensitive operations such as resetting passwords can only be performed by the super administrator.
• Users without an assigned role cannot log in (41003); roles not associated with any menu also cannot log in (41004).

See Permission model for details.

Data source

A data source describes a database connection, including type, host, account, password, connection pool parameters and enabled status. The platform connects heterogeneous databases uniformly through the data source driver SPI.

• The connection must be tested before saving.
• Passwords are stored encrypted, and the frontend never echoes plain text.
• Metadata is expanded in three levels: "database → table → field".
• The data query page only allows read-only statements beginning with SELECT, SHOW, DESC, DESCRIBE or EXPLAIN.

See Data source management and Metadata and data queries for details.

API

An API consists of basic information, request parameters, response parameters, execution configuration and data plugins.

Dimension	Values	Description
Execution type	SQL script / single table / proxy / orchestration	Determines which executor handles it
Request method	GET / POST / PUT / PATCH / DELETE	The available range is narrowed for some types and data sources
Permission level	Public / private	Only APIs that are public and published to production enter API Hub
Authentication method	None / simple / signature	Determines the gateway authentication policy
Publish protocol	REST / MCP	MCP can be selected only with simple authentication
Operation type	Query / insert / update / delete	Not shown for script APIs
Status	In development / published / offline	Offline APIs cannot be called

An API address consists of "environment prefix + project prefix + API path"; within the same environment, "request method + path" must be unique.

Environment

An environment is the isolation dimension for APIs and policy data.

• The system has a built-in dev development environment, which is protected and cannot be deleted.
• Each project initializes dev and a production environment by default; there can be only one production environment and it must be enabled.
• An environment includes: environment code, name, API prefix, access address, bound service name, MCP prefix, whether it is a production environment, and access permission.
• The API list, flow control rules, cache rules, IP rules and alert rules are all displayed and saved according to the currently selected environment.
• An environment with existing APIs cannot be deleted.

See Environments and release for details.

Versions and release snapshots

One API can have multiple versions, and the API addresses of different versions cannot be the same. When publishing to an environment, the platform generates a release snapshot for that environment, recording the complete definition of the API in that environment.

• Changes in development do not automatically affect published snapshots.
• An online API must be taken offline before editing.
• Version upgrades, cross-environment sync, Bundle import/export and offline documentation export are supported.
• The gateway and execution services read the runtime configuration corresponding to the snapshot, not the draft being edited.

See Versions, sync and migration for details.

Credential (App)

A calling credential is the calling identity for open APIs, including AppCode, AppKey, AppSecret, scope, IP allowlist and the MCP switch.

Scope	Accessible range
Project level	APIs in the current project that meet the authorization conditions
API level	Only APIs that are explicitly authorized

• Simple authentication: only X-AppKey is passed.
• Signature authentication: pass X-AppKey, X-Timestamp, X-Nonce and X-Sign, and optionally X-Algorithm.
• After a credential is disabled, all calls return 40019.
• After MCP is enabled for a credential, it can be used as an MCP Server.

See Credentials for details.

Subscription

For APIs that require control, callers must submit a subscription application and have it approved.

Status	Meaning
pending	Awaiting approval, can be withdrawn
active	In effect, subject to the validity period and daily call volume
rejected	Rejected, can be reapplied
frozen	Frozen, calls return 40021
expired	Expired, can be renewed
unsubscribed	Unsubscribed

Only one valid subscription can exist for the same credential and the same API. Daily call volume is atomically reserved through Redis Lua; exceeding the limit returns HTTP 429 + 40023; downstream failures roll back the quota.

See Subscriptions and approval for details.

Governance rules

Gateway governance rules are isolated by environment and associated with APIs:

Rule	Effect	Over-limit response
Flow control	Limits QPS	429 + 40429
Circuit breaking and degradation	Slow call ratio, exception ratio, exception count	503 + 40503
API cache	Caches JSON query results in Redis	Adds Api-Cache: true on a cache hit
IP rules	API-level deny/allow lists	40012
Alert rules	Trigger notifications based on log metrics	Generates alert records

• Rules take effect only after being associated with an API; one API can be associated with only one rule of each type.
• When an API has multiple versions, rules apply only to the latest version.
• Rules already associated with an API cannot be deleted directly; you must remove the association first.

Runtime configuration and trace

After the admin side saves configuration, it is written to MySQL and synchronized to the Redis runtime hub, which incrementally notifies the gateway and execution services through Pub/Sub.

• The gateway matches dynamic routes by "request method + path".
• Each request can carry X-Trace-Id; if it is not provided, the platform generates one and returns it in the traceId field of the response body.
• API logs record the request, response, elapsed time, status and source (rest / mcp).
• Configuration changes take effect immediately without restarting services; scheduled reconciliation ensures eventual consistency between Redis and MySQL.

AI and sessions

• AI assistant: plans and calls platform tools in a conversational way, supporting data queries, log queries, API development and other operations.
• Data query tool: generates read-only SQL for a specified data source, displays results as tables/charts, and allows editing the SQL before previewing again.
• Agent: the identity through which an external AI Agent accesses platform management capabilities, using platform tools through MCP.
• Sessions and AI logs are isolated by user and project; write operations require manual confirmation.

See AI assistant and Agent management for details.

Glossary

Term	Meaning
API Hub	A portal that exposes public, production, online APIs
Release snapshot	A read-only published version of an API in a specific environment
Runtime configuration	Configuration in Redis that the gateway and execution services read
Tool timeline	Entries in the AI assistant that show each tool call process
MCP Tool	A callable tool exposed to AI clients through the MCP protocol
Quota reservation	Atomically deducting the daily subscription quota before a call, rolled back on failure
Trusted proxy	Only forwarding headers from trusted network segments are accepted, used to identify the real client IP