API 服务 ​

状态：待开发。 当前只有 services/ontology-api/ 目录骨架。

对外提供 REST/OpenAPI 入口，负责请求校验、身份与租户上下文、限流信息传递及调用编排。模型发布、查询、回写和权限决策由对应服务执行；接口定义以未来的 contracts/openapi/ 为准。

负责范围 ​

• 验证访问令牌、服务身份和委托上下文，建立可信 AuthContext。
• 解析 API 版本、租户、模型版本、幂等键和追踪头。
• 完成请求 Schema 校验、限流、配额预检和稳定错误映射。
• 将模型请求交给 Registry，读取请求交给 Runtime，动作请求交给 Actions。
• 提供异步执行状态、分页、请求取消和 Webhook 注册入口。

不负责语义查询规划、策略求值、连接器执行、模型发布事务和 Action 状态机，也不直接访问这些服务的数据表。

计划接口 ​

接口族包括本体与版本、实体与关系查询、Function 调用、Action 提交与状态、工具目录以及管理接口。机器定义放在 contracts/openapi/；REST、SDK 和文档从同一契约生成。

响应统一返回 traceId。Action 提交接受调用方幂等键并返回 executionId。错误响应包含稳定错误码、可重试标记和安全的诊断信息，不暴露内部堆栈或连接器凭据。

数据与依赖 ​

API 服务只保存短期限流或请求状态，不拥有业务事实。它依赖身份提供方、Control Plane、Registry、Runtime、Actions 和 MCP 服务；下游不可用时按操作类型快速失败或返回异步状态，不自行重放有副作用请求。

验收重点 ​

• 伪造租户和主体字段不会覆盖令牌中的可信上下文。
• OpenAPI 与实现通过契约测试。
• 超限、无权限、下游超时和版本不匹配有稳定错误语义。
• 日志和指标可以按租户、接口、状态码和 traceId 定位问题。