API Design for FDE（FDE 场景下的 API 设计）

知识库位置：FDE Knowledge Base/03 Engineering/Software Engineering/API/API-Design.md

API（Application Programming Interface，应用程序编程接口）是 FDE 项目中最常见的系统连接方式之一。

无论是连接 CRM（Customer Relationship Management，客户关系管理系统）、ERP（Enterprise Resource Planning，企业资源计划系统）、数据库服务，还是把 AI Agent（AI 智能体）接入业务系统，API 通常都是基础接口。

FDE 不仅需要知道如何调用 API，还需要理解：

API 如何成为系统之间稳定的契约（Contract，契约）。

Why It Matters（为什么重要）

在客户项目中，常见场景包括：

从 CRM 获取客户信息
从 ERP 查询订单
调用内部审批系统
调用第三方（Third-party，第三方）SaaS（Software as a Service，软件即服务）
暴露 AI 服务
为 Agent 提供工具接口

API 设计质量会直接影响：

系统稳定性（Stability，稳定性）
集成难度
可维护性（Maintainability，可维护性）
安全性
扩展能力

Core Concepts（核心概念）

Endpoint（接口端点）

例如：

GET /customers/{id}
POST /orders
POST /agents/run

Request（请求）

客户端传入的数据。

Response（响应）

服务端返回的数据。

Status Code（状态码）

例如：

200 Success（成功）
400 Bad Request（错误请求）
401 Unauthorized（未认证）
403 Forbidden（已认证但无权限）
404 Not Found（资源不存在）
500 Internal Server Error（服务器内部错误）

Contract（契约）

API 应该明确：

输入（Input，输入）
输出（Output，输出）
错误（Error，错误）
权限（Permission，权限）
Version（版本）

Good API Design（好的 API 设计）

好的 API 应该尽量：

Predictable（可预测）
Consistent（一致）
Explicit（明确）
Versioned（有版本管理）
Observable（可观测）
Secure（安全）

Example（示例）

客户希望 AI Agent 查询订单状态。

不建议让 Agent 直接访问订单数据库。

更合理的是：

AI Agent（AI 智能体）
↓
Order Service API（订单服务 API）
↓
Order Database（订单数据库）

API 可以负责：

权限检查（Permission Check，权限检查）
参数校验（Parameter Validation，参数校验）
数据过滤（Data Filtering，数据过滤）
日志（Logging，日志记录）
Audit（审计）

Common Mistakes（常见错误）

常见问题：

Agent 直接访问数据库
返回过多敏感字段
没有权限检查
Error Message（错误信息）不统一
没有 Timeout（超时）
API 没有版本管理（Versioning，版本管理）
一个 Endpoint（接口端点）承担太多责任

FDE Decision（FDE 决策要点）

设计 API 时应该问：

这个接口是一次性的项目接口，还是未来会被多个系统复用？

如果会复用，应提高接口设计标准。