接口文档模板RESTful规范十个完整接口示例与错误码表.docx

RESTful接口文档模板：规范十个完整接口示例请求响应与错误码表

我做了12年后端开发，对外提供过的API服务过30多个合作方，也对接过上百个第三方接口。接口文档是前后端、甲乙方的合同——文档写得糊，联调就是互相折磨（你文档里没说这个字段必填啊！）；文档写得清，联调一天通关。这份模板按RESTful最佳实践编写，含10个完整接口示例和统一错误码表，可直接套用。

一、接口设计规范（八条约定）

一、URL规范：资源名用复数名词（/api/v1/orders），动作用子资源或参数表达，不在URL里出现动词（/getOrder是反模式）；二、方法语义：GET查询、POST创建、PUT全量更新、PATCH部分更新、DELETE删除；三、版本管理：URL带版本号（/v1/），向后兼容原则，破坏性变更升版本；四、请求规范：Body用JSON，字符集UTF-8，时间格式ISO8601（2026-10-09T10:30:00+08:00）；五、响应规范：统一包裹结构{code,message,data}；六、认证方式：BearerToken（JWT），Token有效期2小时，RefreshToken30天；七、限流规则：单应用默认1000次/分钟，超限返回429；八、幂等要求：写操作支持Idempotency-Key请求头，防止重试产生重复数据。

二、完整接口示例（10个，订单域）

【