基础: 1.总使用TLS(https)访问API,对于非TLS请求返回403而不是重定向(使流量翻倍,敏感数据在第一次请求时已经发出) 2.通过Etags缓存 3.使用request-ids追踪请求 4.用Ranges来分页
请求: 1.返回适当的状态码:示例 (1)200: 当GET请求成功完成，DELETE或者PATCH请求同步完成 (2)201: 同步方式成功完成POST请求。 (3)202: POST，DELETE或者PATCH请求提交成功，稍后将异步的进行处理。 (4)206: GET请求成功完成，但只返回了部分数据 (5)401 Unauthorized: 请求失败，因为用户没有进行认证。 (6)403 Forbidden: 请求失败，因为用户被认定没有访问特定资源的权限。 (7)422 Unprocessable Entity: 你的请求服务器可以理解，但是其中包含了不合法的参数。 (8)429 Too Many Requests: 请求频率超配，稍后再试。 (9)500 Internal Server Error: 服务器出错了，检查网站的状态，或者报告问题。 2.总是返回完整的资源(完整定义:某属性为对象,则展示该对象所有属性)200/1,而非202 3.在请求body中接收JSON序列(现在ajax请求很方便,统一格式比杂乱要好,减少后台处理的复杂程度) 4.使用一致的路径格式(一股restful API感觉) (1)资源名称: 使用复数来命名资源，除非该资源在系统中是单件(如账户),引用特定资源时可以保持一致 (2)动作: 独有资源不需要使用特定动作的endpoint格式。当需要特定的动作，只需要把它们放到标准的actions前缀后边，便可清晰描述. 如:/resources/:resource/actions/:action 5.小写所有路径和属性: 减号命名路径,下划线来分割 6.支持非ID的参数作为快捷方式(id可能会非常复杂,需要提供更便捷的方式),绝不要只接收名称来排除某些ID??? 7.少用路径嵌套(可能深度嵌套,考虑根路径定位,嵌套限定数据集)
响应; 1.总是提供资源(UU)ID??? 2.提供标准的时间戳(created_at 和 updated_at) 3.使用ISO8601格式的UTC时间 4.嵌入外键数据(外键?? ) 如:”name_id”:’234sfd’ 改 name:{id:’123asldjf’} 当name属性扩展时无需改变响应格式 5.总是生成结构化的错误信息: 结构化的响应Body。包含机器可读的id，人类可读的message，以及可选的url指向关于错误的更多信息，还有如何解决它.为客户端常见的错误的格式和id撰写文档 6.显示频率限制的状态(保护服务健康,)响应头中，通过RateLimit-Remaining 返回剩余的请求次数 7.在所有的响应中压缩JSON数据(可以通过额外参数,或accept头切换) 8.提供可执行示例(最小化用户试用API的成本)