[最新]API设计原则.ppt

API设计原则;为什么设计api？;api存在的形态？无处不在;优秀API所具备的特征？;API设计通用原则;3.兼容性：向后兼容 4.文档：对外提供清晰的API和文档规范，避免用户错误的使用API，尤其是避免API靠后级别的API被用户知晓与误用；SDK，console tools 5.可测试性：不依赖实现 6.职责明确：一个接口实现一个业务 7.高内聚低耦合：一个接口实现一个完整的业务功能，而不是多个接口调用 ;8.参数格式统一：不要一会儿逗号分隔，一会儿数组；日期一会儿是yyyyMMdd，yyyy-MM-dd 9.状态和消息：告知用户成功还是失败，失败原因 10.控制数据量：过多数据传输压力大，客户端反应缓慢，是否接口划分不明？ 11.禁止随意扩展api和参数：新建接口要有充分理由和考虑，加参数必要要有意思，首先应考虑现有内部接口维护是否能满足，不要为了方便实现加参数 ;HTTP API设计原则;6.过滤(filter)： limit,offset,page,per_page,sortby,order,animal_type_id 7.状态码（status code）： 8.错误处理(error handling)： { error: Invalid API key } 9.数据格式：json,避免xml 10.时间格式：不同时区人调用，使用UTC时间 ;200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务） 204 NO CONTENT - [DELETE]：用户删除数据成功。 400 INVALID REQUEST - [POST/PUT/PATCH]用户发出的请求有错误 401 Unauthorized - [*] 用户没有权限（令牌、用户名、密码错误） 403 Forbidden - [*] 用户得到授权，但是访问是被禁止的 404 NOT FOUND - [*]不存在的记录 406 Not Acceptable - [GET]用户请求的格式错误 410 Gone -[GET]用户请求的资源被永久删除 422 Unprocesable entity - [POST/PUT/PATCH]当创建一个对象时，发生一个验证错误 500 INTERNAL SERVER ERROR - [*] 服务器发生错误 ;11.外键数据，便于扩展： { name: service-production, owner: { id: 5d8201b0... } } 而不是 { name: service-production, owner_id: 5d8201b0..., ... } ;12.限制调用次数：token bucket 算法 ，RateLimit-Remaining 返回剩余的请求次数 13.压缩json数据：回车空格去掉 14.提供文档和工具：保持更新，提供sdk，console工具 ;谢谢!